lex-app 2.2.0__tar.gz → 2.2.2__tar.gz

lex_app-2.2.2/MANIFEST.in

@@ -0,0 +1,15 @@
+recursive-include lex/react *
+# The compiled SPA is NOT shipped in the distribution. It arrives as the
+# lex-app-frontend dependency, pinned in requirements.txt, and shipping a
+# second copy meant every release carried a frozen bundle that nothing served
+# — 57% of the wheel, stale from the day it was built.
+#
+# It stays in the source tree: settings.py falls back to it so a git checkout
+# works without installing the frontend package.
+recursive-exclude lex/react/build *
+recursive-include lex/assets *
+include pyproject.toml
+include requirements*.txt
+include generate_pycharm_configs.py
+global-exclude __pycache__ *.py[cod] .DS_Store
+recursive-exclude * __pycache__

{lex_app-2.2.0/lex_app.egg-info → lex_app-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lex-app
-Version: 2.2.0
+Version: 2.2.2
 Summary: A Python / Django library to create business applications easily with complex logic
 Author-email: Melih Sünbül <m.sunbul@excellence-cloud.com>
 License-Expression: MIT
@@ -60,6 +60,7 @@ Requires-Dist: psycopg2-binary
 Requires-Dist: django-celery-beat
 Requires-Dist: pytest
 Requires-Dist: cryptography
+Requires-Dist: lex-app-frontend~=2.2.0
 Dynamic: license-file
 
 LEX App Documentation - Previously known as DPAG :)

lex_app-2.2.2/lex/_version.py

@@ -0,0 +1 @@
+__version__ = "2.2.2"

{lex_app-2.2.0 → lex_app-2.2.2}/lex/api/serializers/base_serializers.py

@@ -7,6 +7,7 @@ from django.db.models import Model, ForeignKey
 from django.db.models.fields import DateTimeField, DateField, TimeField
 from lex.api.utils.helpers import can_read_with_default_permission_scope
 from lex.audit_logging.utils.content_types import safe_get_content_type
+from lex.audit_logging.utils.latest_calculation import is_calculation_model
 from lex.core.models.LexModel import LexModel, UserContext
 from rest_framework import serializers, viewsets
 
@@ -21,6 +22,10 @@ from lex.api.serializers.sensitive_fields import (
 ID_FIELD_NAME = "id_field"
 SHORT_DESCR_NAME = "short_description"
 LEX_SCOPES_NAME = "lex_reserved_scopes"
+# The newest run a calculation row started, and whether it has one. Declared
+# only on serializers of CalculationModel subclasses; see _calculation_run_fields.
+CALCULATION_ID_NAME = "lex_reserved_calculation_id"
+HAS_CALCULATION_LOG_NAME = "lex_reserved_has_calculation_log"
 
 # --- MODULE-LEVEL CACHES (populated lazily, persist for process lifetime) ---
 
@@ -39,6 +44,28 @@ def _get_lexmodel_fields() -> set:
     return _lexmodel_fields
 
 
+def _calculation_run_fields(model) -> dict:
+    """The two latest-run fields, for calculation models only.
+
+    Values are read from attributes the list view sets for a whole page at
+    once (``annotate_latest_calculation``). Nothing here queries per row.
+    """
+    if not is_calculation_model(model):
+        return {}
+    # Explicit method names, deliberately not the get_<field> defaults:
+    # _wrap_custom_serializer builds (LexSerializer, custom_cls), so a method
+    # named get_lex_reserved_has_calculation_log on LexSerializer would come
+    # first in the MRO and shadow AuditLogDefaultSerializer's own getter.
+    return {
+        CALCULATION_ID_NAME: serializers.SerializerMethodField(
+            method_name="_lex_latest_calculation_id"
+        ),
+        HAS_CALCULATION_LOG_NAME: serializers.SerializerMethodField(
+            method_name="_lex_has_latest_calculation_log"
+        ),
+    }
+
+
 # Cache: model-name -> model-class lookup for _resolve_target_model
 _model_lookup: dict | None = None
 
@@ -364,6 +391,17 @@ class LexSerializer(serializers.ModelSerializer):
 
         return target
 
+    # ------------------------------------------------------------------
+    # Latest calculation run — read through method_name, see _calculation_run_fields
+    # ------------------------------------------------------------------
+    def _lex_latest_calculation_id(self, instance):
+        """The newest run started from this row, when the list resolved it."""
+        return getattr(instance, "_lex_calculation_id", None)
+
+    def _lex_has_latest_calculation_log(self, instance):
+        """Whether that run exists. Unannotated rows answer False, never a query."""
+        return bool(getattr(instance, "_has_calculation_log", False))
+
     # ------------------------------------------------------------------
     # Scopes computation
     # ------------------------------------------------------------------
@@ -680,7 +718,10 @@ class LexSerializer(serializers.ModelSerializer):
     _SYSTEM_FIELDS = frozenset({
         'history_id', 'history_date', 'history_type', 'history_user', 'history_change_reason',
         'valid_from', 'valid_to',
-        'calculation_record', 'lex_reserved_scopes', 'id', 'id_field', SHORT_DESCR_NAME
+        'calculation_record', 'lex_reserved_scopes', 'id', 'id_field', SHORT_DESCR_NAME,
+        # Without these two, to_representation's visibility filter strips the
+        # run fields silently and the log button never appears.
+        CALCULATION_ID_NAME, HAS_CALCULATION_LOG_NAME,
     })
 
     def to_representation(self, instance):
@@ -870,13 +911,17 @@ def model2serializer(model, fields=None, name_suffix=""):
     pk_alias = serializers.ReadOnlyField(default=model._meta.pk.name)
 
     # ensure our internal fields are always present
-    all_fields = list(fields) + [ID_FIELD_NAME, SHORT_DESCR_NAME, "id", LEX_SCOPES_NAME]
+    run_fields = _calculation_run_fields(model)
+    all_fields = list(fields) + [
+        ID_FIELD_NAME, SHORT_DESCR_NAME, "id", LEX_SCOPES_NAME, *run_fields,
+    ]
 
     return type(
         class_name,
         (RestApiModelSerializerTemplate,),
         {
             ID_FIELD_NAME: pk_alias,
+            **run_fields,
             "Meta": type(
                 "Meta",
                 (RestApiModelSerializerTemplate.Meta,),
@@ -888,11 +933,12 @@ def model2serializer(model, fields=None, name_suffix=""):
 
 def _wrap_custom_serializer(custom_cls, model_class):
     meta = getattr(custom_cls, "Meta", type("Meta", (), {}))
+    run_fields = _calculation_run_fields(model_class)
     existing_fields = getattr(meta, "fields", "__all__")
     if existing_fields != "__all__":
         existing = list(existing_fields)
         # make sure all internal fields are present, including lex_reserved_scopes
-        for extra in (ID_FIELD_NAME, SHORT_DESCR_NAME, "id", LEX_SCOPES_NAME):
+        for extra in (ID_FIELD_NAME, SHORT_DESCR_NAME, "id", LEX_SCOPES_NAME, *run_fields):
             if extra not in existing:
                 existing.append(extra)
         new_fields = existing
@@ -935,6 +981,7 @@ def _wrap_custom_serializer(custom_cls, model_class):
         ID_FIELD_NAME: serializers.ReadOnlyField(default=model_class._meta.pk.name),
         SHORT_DESCR_NAME: serializers.SerializerMethodField(),
         "get_short_description": lambda self, obj: str(obj),
+        **run_fields,
         "Meta": NewMeta,
     }
     # Use a bare ``ReadOnlyField()`` (DRF defaults ``source`` to the field

{lex_app-2.2.0 → lex_app-2.2.2}/lex/api/views/model_entries/List.py

@@ -892,7 +892,22 @@ class ListModelEntries(ModelEntryProviderMixin, ListAPIView):
 
         row_count = qs.count()
         page_qs = qs[start_row:end_row]
-        serializer = self.get_serializer(page_qs, many=True)
+
+        from lex.audit_logging.utils.latest_calculation import (
+            annotate_latest_calculation,
+            is_calculation_model,
+        )
+
+        if is_calculation_model(self._ag_model_class):
+            # A calculation row carries only `is_calculated`; the grid needs to
+            # know which rows have a finished log to open. Resolved for the
+            # whole page in one query and set on the instances the serializer
+            # reads — the same shape as the audit log branch above.
+            page_rows = list(page_qs)
+            annotate_latest_calculation(page_rows, self._ag_model_class)
+            serializer = self.get_serializer(page_rows, many=True)
+        else:
+            serializer = self.get_serializer(page_qs, many=True)
         return {
             "rowData": serializer.data,
             "rowCount": row_count,

{lex_app-2.2.0 → lex_app-2.2.2}/lex/audit_logging/models/CalculationLog.py

@@ -203,6 +203,59 @@ class CalculationLog(models.Model):
             log_entry.calculation_log = (log_entry.calculation_log or "") + f"\n{message}"
             log_entry.save(update_fields=["calculation_log"])
 
+    @classmethod
+    def keep_rolled_back_log(cls, calculation_id, root_record, root_instance) -> bool:
+        """
+        Keep what a failed run logged when its transaction took the rows with it.
+
+        `log` persists on commit, so a calculation that fails inside its
+        transaction — every `is_atomic` model — is rolled back with every row it
+        wrote: the steps that succeeded vanish with the one that failed. The live
+        cache is not transactional. It holds the run's whole log, in order, under
+        the root's key until the run ends, so the failure paths call this just
+        before they purge it, and it writes that text back as the run's log: one
+        row on the root record, the same text the live stream showed.
+
+        Does nothing when rows for the run survived (a run outside a transaction
+        keeps them) or when the cache holds nothing for it. Never raises — a
+        failure path must not fail again on its way to reporting the first one.
+        """
+        logger = logging.getLogger("lex.calclog")
+        try:
+            if not calculation_id or not root_record or root_instance is None:
+                return False
+            if cls.objects.filter(calculationId=calculation_id).exists():
+                return False
+            text = CacheManager.get_message(
+                CacheManager.build_cache_key(root_record, calculation_id)
+            )
+            if not text:
+                return False
+
+            from lex.audit_logging.models.AuditLog import AuditLog
+
+            # The run's first audit row was written by the request that started
+            # it, before the transaction, so it survived; rows the calculation
+            # wrote itself went with the rollback.
+            audit_log = (
+                AuditLog.objects.filter(calculation_id=calculation_id).order_by("id").first()
+            )
+            cls.objects.create(
+                calculationId=calculation_id,
+                audit_log=audit_log,
+                content_type=ContentType.objects.get_for_model(type(root_instance)),
+                object_id=root_instance.pk,
+                calculation_log=text,
+            )
+            return True
+        except Exception:
+            logger.warning(
+                "Could not keep the log of failed calculation %s",
+                calculation_id,
+                exc_info=True,
+            )
+            return False
+
     @classmethod
     def log(cls, message: str):
         """

lex_app-2.2.2/lex/audit_logging/utils/latest_calculation.py

@@ -0,0 +1,105 @@
+"""The newest calculation run started from each record on a page.
+
+A calculation row carries ``is_calculated`` and nothing else, so on its own the
+grid cannot tell which rows have a finished log to open. This resolves, for a
+whole page of rows in one query, the ``calculationId`` of the newest run each
+row started.
+
+The rule is the one ``useResolvedCalculationId`` applies in the frontend,
+stated here in Python so the table and every widget open the same run for the
+same row: a run started from record ``pk`` of model ``m`` has an id beginning
+``f"{m}_{pk}_"`` (the frontend mints ``{m}_{pk}_update_{uuid}``), and the newest
+is the one with the highest ``CalculationLog.id``.
+
+The trailing underscore is load-bearing: without it, record 1 would match
+record 11's runs.
+
+Served by the index ``calculationId`` already has (migration 0005). On
+PostgreSQL, Django adds a ``text_pattern_ops`` companion index for an indexed
+text field, and that is what serves ``LIKE 'prefix%'``.
+"""
+from __future__ import annotations
+
+import logging
+from functools import reduce
+from operator import or_
+from typing import Dict, Iterable, Tuple
+
+from django.db.models import Max, Q
+
+logger = logging.getLogger(__name__)
+
+
+def is_calculation_model(model) -> bool:
+    """Whether ``model`` is a ``CalculationModel`` subclass.
+
+    Imported lazily: ``lex.core.models.CalculationModel`` pulls in much of the
+    framework, and the serializer layer imports this module.
+    """
+    from lex.core.models.CalculationModel import CalculationModel
+
+    return isinstance(model, type) and issubclass(model, CalculationModel)
+
+
+def run_prefix(model_name: str, pk: object) -> str:
+    """The id prefix every run started from this record carries."""
+    return f"{model_name}_{pk}_"
+
+
+def latest_calculation_ids(model_name: str, pks: Iterable[object]) -> Dict[str, str]:
+    """Map ``str(pk)`` to the ``calculationId`` of the newest run it started.
+
+    Records that never started a run are absent. One query whatever the number
+    of records: one ``startswith`` per record, ORed, collapsed to one row per
+    run before it leaves the database.
+    """
+    from lex.audit_logging.models.CalculationLog import CalculationLog
+
+    prefixes = {str(pk): run_prefix(model_name, pk) for pk in pks}
+    if not prefixes:
+        return {}
+
+    runs = (
+        CalculationLog.objects.filter(
+            reduce(or_, (Q(calculationId__startswith=p) for p in prefixes.values()))
+        )
+        .values("calculationId")
+        .annotate(newest=Max("id"))
+    )
+
+    # Longest prefix first. For string keys containing "_", a run id can start
+    # with two of the page's prefixes ("m_a_" and "m_a_b_"); the longer one is
+    # the record that started it, because record "a"'s own runs begin
+    # "m_a_update_". Integer keys cannot collide.
+    by_length = sorted(prefixes.items(), key=lambda item: len(item[1]), reverse=True)
+    best: Dict[str, Tuple[int, str]] = {}
+    for run in runs:
+        calculation_id = run["calculationId"]
+        for pk, prefix in by_length:
+            if calculation_id.startswith(prefix):
+                if pk not in best or run["newest"] > best[pk][0]:
+                    best[pk] = (run["newest"], calculation_id)
+                break
+    return {pk: calculation_id for pk, (_, calculation_id) in best.items()}
+
+
+def annotate_latest_calculation(rows, model) -> None:
+    """Set ``_lex_calculation_id`` and ``_has_calculation_log`` on each row.
+
+    Never raises. A failure costs the log button, not the page: every row is
+    marked as having no log and the grid still loads.
+    """
+    try:
+        ids = latest_calculation_ids(model._meta.model_name, [row.pk for row in rows])
+    except Exception:
+        logger.warning(
+            "Could not resolve the latest calculation runs for %s; "
+            "serving the page without them.",
+            model._meta.label,
+            exc_info=True,
+        )
+        ids = {}
+    for row in rows:
+        calculation_id = ids.get(str(row.pk))
+        row._lex_calculation_id = calculation_id
+        row._has_calculation_log = calculation_id is not None

lex_app-2.2.2/lex/core/migrations/0001_bitemporal_activation.py

@@ -0,0 +1,62 @@
+"""
+In-database activation of future-dated bitemporal records.
+
+Installs ``lex/core/sql/bitemporal_activation.sql``: the applier's heartbeat table and
+three pl/pgSQL functions:
+
+    lex_bitemporal_tables()      discovery, from the catalog
+    lex_pending_activations()    visibility: every SCHEDULED row, due or not
+    lex_apply_due_activations()  the applier, called every minute by pg_cron
+
+The SQL is executed through a raw cursor with no parameters: it is full of ``%I`` /
+``%L`` ``format()`` placeholders that psycopg2 would otherwise try to interpolate.
+
+Nothing here is a Django model on purpose. The framework registers every concrete model
+it discovers under ``lex/`` for history tracking and for the model list, and an
+operational heartbeat belongs in neither (see the SQL file). On a non-PostgreSQL backend
+this migration is a no-op: the functions have no equivalent there and the in-process
+fallback keeps working (design §8.13).
+
+Design: docs/superpowers/specs/2026-09-16-bitemporal-activation-applier-design.md
+"""
+
+from pathlib import Path
+
+from django.db import migrations
+
+SQL_PATH = Path(__file__).resolve().parents[1] / "sql" / "bitemporal_activation.sql"
+
+# Drop order: dependants first.
+FUNCTIONS = (
+    "lex_apply_due_activations",
+    "lex_pending_activations",
+    "lex_bitemporal_tables",
+)
+TABLE = "lex_activation_applier_state"
+
+
+def install(apps, schema_editor):
+    if schema_editor.connection.vendor != "postgresql":
+        return
+    with schema_editor.connection.cursor() as cursor:
+        cursor.execute(SQL_PATH.read_text(encoding="utf-8"))
+
+
+def uninstall(apps, schema_editor):
+    if schema_editor.connection.vendor != "postgresql":
+        return
+    with schema_editor.connection.cursor() as cursor:
+        for name in FUNCTIONS:
+            cursor.execute(f"DROP FUNCTION IF EXISTS {name}()")
+        cursor.execute(f"DROP TABLE IF EXISTS {TABLE}")
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.RunPython(install, uninstall),
+    ]

{lex_app-2.2.0 → lex_app-2.2.2}/lex/core/models/CalculationModel.py

@@ -1200,6 +1200,12 @@ class CalculationModel(LexModel):
 
                 if is_root:
                     calc_id = context.calculation_id
+                    # A run that did not succeed was rolled back with its log
+                    # rows; the cache about to be purged still holds the log.
+                    if self.is_calculated != self.SUCCESS:
+                        from lex.audit_logging.models.CalculationLog import CalculationLog
+
+                        CalculationLog.keep_rolled_back_log(calc_id, context.root_record, self)
                     # If we are root, we can clean up everything for this calculation ID
                     # or just our specific key. Cleaning everything ensures no orphaned child keys.
                     cleanup_result = CacheManager.cleanup_calculation(calculation_id=calc_id)
@@ -1432,6 +1438,11 @@ class CalculationModel(LexModel):
 
                 if is_root:
                     calc_id = context.calculation_id
+                    # Same as in execute_calculation_sync, for a failure that
+                    # never reached its cleanup; a no-op once that kept the log.
+                    from lex.audit_logging.models.CalculationLog import CalculationLog
+
+                    CalculationLog.keep_rolled_back_log(calc_id, context.root_record, self)
                     # Clean up all keys associated with this calculation ID
                     cleanup_result = CacheManager.cleanup_calculation(calculation_id=calc_id)
 

{lex_app-2.2.0 → lex_app-2.2.2}/lex/core/services/MetaHistory.py

@@ -12,6 +12,7 @@ The control fields are prefixed with ``meta_`` to avoid collisions with
 the Level 1 fields that are copied into the MetaHistory model.
 """
 
+import hashlib
 import logging
 
 from django.db import models, transaction
@@ -74,6 +75,29 @@ def create_meta_history_record(
     return history_instance
 
 
+def scheduled_activation_index(table_name: str) -> models.Index:
+    """
+    The partial index both activation paths scan every minute, forever.
+
+    ``SELECT ... WHERE meta_task_status = 'SCHEDULED'`` runs per meta table per tick —
+    from the in-database applier (``lex_apply_due_activations()``), from the pending
+    view, and from the reconcile floor. ``SCHEDULED`` rows are transient and rare, so a
+    partial index is tiny and serves the scan and the ``DONE`` flip alike. Declared on
+    the generated model, so every customer repository picks it up as one ``AddIndex``
+    migration per meta table on its next ``makemigrations``. Correctness never depends
+    on it; only the cost of the scan does.
+
+    The name is derived from the table name (Django caps index names at 30 characters
+    and they must be unique per database).
+    """
+    digest = hashlib.md5(table_name.encode("utf-8")).hexdigest()[:12]
+    return models.Index(
+        fields=["history_object"],
+        condition=models.Q(meta_task_status="SCHEDULED"),
+        name=f"lexsched_{digest}",
+    )
+
+
 class MetaLevelHistoricalRecords(HistoricalRecords):
     """
     History-on-History provider.
@@ -170,6 +194,11 @@ class MetaLevelHistoricalRecords(HistoricalRecords):
         meta_fields = super().get_meta_options(model)
         meta_fields["ordering"] = ("-sys_from", "-meta_history_id")
         meta_fields["get_latest_by"] = ("sys_from", "meta_history_id")
+        table_name = self.table_name or f"{model._meta.db_table}_meta_history"
+        meta_fields["indexes"] = [
+            *meta_fields.get("indexes", ()),
+            scheduled_activation_index(table_name),
+        ]
         return meta_fields
 
     # ------------------------------------------------------------------

lex_app-2.2.2/lex/core/services/activation_applier.py

@@ -0,0 +1,167 @@
+"""
+lex-app's side of the in-database activation applier.
+
+The applier itself is SQL (``lex/core/sql/bitemporal_activation.sql``), installed by the
+``lex.core`` migration and called every minute by a pg_cron job the instance controller
+registers. Nothing in this module runs at apply time. What lives here:
+
+* :func:`applier_is_alive` — the **write-time liveness gate**. A future-dated save asks
+  whether the database applied something recently. If yes, the save leaves only the
+  ``SCHEDULED`` meta row: the database will activate it. If no — SQLite, a PostgreSQL
+  without pg_cron, an instance whose job is not registered yet, a migration that has
+  not run — the save also arms the in-process timer it always has. The decision is
+  made from a heartbeat the applier writes on every run, so no configuration can
+  claim an applier that is not there, and the lex-app release is safe to deploy in
+  any order relative to the infrastructure change.
+
+* Thin invokers for tests and operators (:func:`apply_due_activations`,
+  :func:`pending_activations`, :func:`bitemporal_tables`, :func:`install_functions`).
+  They issue one ``SELECT`` each; they add no logic.
+
+Design: docs/superpowers/specs/2026-09-16-bitemporal-activation-applier-design.md (§5.8).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from datetime import timedelta
+from pathlib import Path
+from typing import Any
+
+from django.db import DatabaseError, connection as default_connection, transaction
+from django.utils import timezone
+
+logger = logging.getLogger(__name__)
+
+SQL_PATH = Path(__file__).resolve().parents[1] / "sql" / "bitemporal_activation.sql"
+
+HEARTBEAT_TABLE = "lex_activation_applier_state"
+
+FUNCTION_NAMES = (
+    "lex_bitemporal_tables",
+    "lex_pending_activations",
+    "lex_apply_due_activations",
+)
+
+#: How recent the heartbeat must be for the database applier to count as alive.
+#: pg_cron fires every minute; five minutes absorbs a slow tick or a failover without
+#: arming redundant timers, while a dead applier is noticed within the same window.
+DEFAULT_LIVENESS_WINDOW_SECONDS = 300
+LIVENESS_WINDOW_ENV = "LEX_ACTIVATION_APPLIER_LIVENESS_SECONDS"
+
+
+def liveness_window() -> timedelta:
+    """The heartbeat freshness window, read from the environment on every call."""
+    raw = os.getenv(LIVENESS_WINDOW_ENV, "")
+    try:
+        seconds = int(raw) if raw else DEFAULT_LIVENESS_WINDOW_SECONDS
+    except ValueError:
+        logger.warning("%s=%r is not an integer; using %s", LIVENESS_WINDOW_ENV, raw,
+                       DEFAULT_LIVENESS_WINDOW_SECONDS)
+        seconds = DEFAULT_LIVENESS_WINDOW_SECONDS
+    return timedelta(seconds=max(seconds, 0))
+
+
+def applier_is_alive(*, now=None, using=None) -> bool:
+    """
+    True when the database applier has run within :func:`liveness_window`.
+
+    False on any non-PostgreSQL backend, when the heartbeat table is missing (the
+    migration has not run), when it is empty (the applier has never run), or when the
+    last run is older than the window. Never raises: the query runs in a savepoint so a
+    missing table cannot poison the caller's transaction, and a database error simply
+    means "not alive", which falls back to the behaviour lex-app has always had.
+    """
+    conn = default_connection if using is None else transaction.get_connection(using)
+    if conn.vendor != "postgresql":
+        return False
+    try:
+        with transaction.atomic(using=conn.alias), conn.cursor() as cursor:
+            cursor.execute(f"SELECT last_run_at FROM {HEARTBEAT_TABLE} WHERE id = 1")
+            row = cursor.fetchone()
+    except DatabaseError as exc:  # table not migrated yet, connection trouble, ...
+        logger.debug("Activation applier liveness unknown (%s); treating as not alive", exc)
+        return False
+    if row is None:
+        return False
+    now = now or timezone.now()
+    return (now - row[0]) <= liveness_window()
+
+
+def _rows(cursor) -> list[dict[str, Any]]:
+    columns = [col[0] for col in cursor.description]
+    return [dict(zip(columns, row)) for row in cursor.fetchall()]
+
+
+# ── heartbeat access (operators and tests; the applier itself writes it in SQL) ──
+
+
+def read_heartbeat(using=None) -> dict[str, Any] | None:
+    """The heartbeat row as a dict, or None when the applier has never run."""
+    conn = default_connection if using is None else transaction.get_connection(using)
+    with conn.cursor() as cursor:
+        cursor.execute(
+            f"SELECT last_run_at, last_run_applied, last_run_failed, last_run_duration_ms "
+            f"FROM {HEARTBEAT_TABLE} WHERE id = 1"
+        )
+        rows = _rows(cursor)
+    return rows[0] if rows else None
+
+
+def record_heartbeat(*, last_run_at=None, applied: int = 0, failed: int = 0,
+                     duration_ms: int = 0, using=None) -> None:
+    """Write the heartbeat row as the applier would. Used to simulate a live applier."""
+    conn = default_connection if using is None else transaction.get_connection(using)
+    with conn.cursor() as cursor:
+        cursor.execute(
+            f"INSERT INTO {HEARTBEAT_TABLE} (id, last_run_at, last_run_applied, last_run_failed, last_run_duration_ms) "
+            f"VALUES (1, %s, %s, %s, %s) "
+            f"ON CONFLICT (id) DO UPDATE SET last_run_at = EXCLUDED.last_run_at, "
+            f"last_run_applied = EXCLUDED.last_run_applied, last_run_failed = EXCLUDED.last_run_failed, "
+            f"last_run_duration_ms = EXCLUDED.last_run_duration_ms",
+            [last_run_at or timezone.now(), applied, failed, duration_ms],
+        )
+
+
+def clear_heartbeat(using=None) -> None:
+    """Remove the heartbeat row: the state before the applier has ever run."""
+    conn = default_connection if using is None else transaction.get_connection(using)
+    with conn.cursor() as cursor:
+        cursor.execute(f"DELETE FROM {HEARTBEAT_TABLE} WHERE id = 1")
+
+
+# ── thin invokers ──────────────────────────────────────────────────────────────
+
+
+def install_functions(using=None) -> None:
+    """(Re)install the SQL functions from :data:`SQL_PATH`. PostgreSQL only."""
+    conn = default_connection if using is None else transaction.get_connection(using)
+    if conn.vendor != "postgresql":
+        raise RuntimeError("The activation applier is PostgreSQL-only")
+    with conn.cursor() as cursor:
+        cursor.execute(SQL_PATH.read_text(encoding="utf-8"))
+
+
+def apply_due_activations(using=None) -> int:
+    """Run one applier tick. Returns the number of records converged."""
+    conn = default_connection if using is None else transaction.get_connection(using)
+    with conn.cursor() as cursor:
+        cursor.execute("SELECT lex_apply_due_activations()")
+        return int(cursor.fetchone()[0])
+
+
+def pending_activations(using=None) -> list[dict[str, Any]]:
+    """Every SCHEDULED meta row across every bitemporal table, due or not."""
+    conn = default_connection if using is None else transaction.get_connection(using)
+    with conn.cursor() as cursor:
+        cursor.execute("SELECT * FROM lex_pending_activations()")
+        return _rows(cursor)
+
+
+def bitemporal_tables(using=None) -> list[dict[str, Any]]:
+    """The (main, history, meta, pk) triples the applier discovers right now."""
+    conn = default_connection if using is None else transaction.get_connection(using)
+    with conn.cursor() as cursor:
+        cursor.execute("SELECT * FROM lex_bitemporal_tables()")
+        return _rows(cursor)