superlocalmemory 3.7.8 → 3.8.1

package/src/superlocalmemory/retrieval/semantic_channel.py

@@ -120,6 +120,8 @@ class SemanticChannel:
         query_embedding: list[float],
         profile_id: str,
         top_k: int = 50,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
         """Search for semantically similar facts.
 
@@ -130,11 +132,23 @@ class SemanticChannel:
             query_embedding: Dense vector for the query.
             profile_id: Scope to this profile.
             top_k: Maximum results to return.
+            include_global: Include global-scope facts. Defaults to the
+                ``include_global`` instance attribute when not supplied,
+                preserving backward compatibility for callers that still
+                set the attribute directly.
+            include_shared: Include shared-scope facts. Same fallback.
 
         Returns:
             List of (fact_id, score) sorted by score descending.
             Score is in [0, 1] range.
         """
+        # Resolve scope flags: explicit param takes priority; fall back to the
+        # legacy attribute-based path so existing callers keep working.
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
+
         if not query_embedding:
             return []
 
@@ -142,16 +156,26 @@ class SemanticChannel:
 
         # Lance is a derived projection.  It is never an authorization source
         # and it never silently replaces the canonical sqlite-vec path: every
-        # promoted query is shadowed and falls back if membership/order differs.
+        # promoted query is shadowed and falls back if the result *membership*
+        # differs. Order differences within the same fact set are tolerated —
+        # float-score ties would otherwise force a fallback on every query,
+        # leaving the promoted backend permanently unused. Once membership
+        # matches, the projected backend's own ranking is authoritative.
         if (
             self._scale_vector_backend is not None
-            and not bool(getattr(self, "include_global", False))
-            and not bool(getattr(self, "include_shared", False))
+            and not include_global
+            and not include_shared
         ):
-            projected = self._search_via_lance(query_embedding, q_vec, profile_id, top_k)
-            canonical = self._search_without_lance(query_embedding, q_vec, profile_id, top_k)
+            projected = self._search_via_lance(
+                query_embedding, q_vec, profile_id, top_k,
+                include_global=include_global, include_shared=include_shared,
+            )
+            canonical = self._search_without_lance(
+                query_embedding, q_vec, profile_id, top_k,
+                include_global=include_global, include_shared=include_shared,
+            )
             self._scale_shadow_checks += 1
-            if [fid for fid, _ in projected] == [fid for fid, _ in canonical]:
+            if {fid for fid, _ in projected} == {fid for fid, _ in canonical}:
                 return projected
             self._scale_shadow_mismatches += 1
             logger.warning("Lance semantic projection diverged from SQLite; using SQLite")
@@ -161,13 +185,17 @@ class SemanticChannel:
         if self._vector_store and self._vector_store.available:
             results = self._search_via_vector_store(
                 query_embedding, q_vec, profile_id, top_k,
+                include_global=include_global, include_shared=include_shared,
             )
             if results:  # If vec0 returned results, use them
                 return results
             # If vec0 is empty (cold start), fall through to full scan
 
         # --- FALLBACK: full-table scan (original code, unchanged) ---
-        return self._search_full_scan(query_embedding, q_vec, profile_id, top_k)
+        return self._search_full_scan(
+            query_embedding, q_vec, profile_id, top_k,
+            include_global=include_global, include_shared=include_shared,
+        )
 
     def set_scale_vector_backend(self, backend: Any | None) -> None:
         """Attach a parity-verified Lance projection without replacing SQLite."""
@@ -180,14 +208,27 @@ class SemanticChannel:
         }
 
     def _search_via_lance(
-        self, query_embedding: list[float], q_vec: np.ndarray, profile_id: str, top_k: int,
+        self,
+        query_embedding: list[float],
+        q_vec: np.ndarray,
+        profile_id: str,
+        top_k: int,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         original_store, original_qas = self._vector_store, self._qas
         try:
             self._vector_store = _LanceCandidateSource(self._scale_vector_backend)
             # QAS indexes SQLite/quantized records and cannot represent Lance.
             self._qas = None
-            return self._search_via_vector_store(query_embedding, q_vec, profile_id, top_k)
+            return self._search_via_vector_store(
+                query_embedding, q_vec, profile_id, top_k,
+                include_global=include_global, include_shared=include_shared,
+            )
         except Exception as exc:
             logger.warning("Lance semantic projection failed closed to SQLite: %s", exc)
             return []
@@ -195,15 +236,31 @@ class SemanticChannel:
             self._vector_store, self._qas = original_store, original_qas
 
     def _search_without_lance(
-        self, query_embedding: list[float], q_vec: np.ndarray, profile_id: str, top_k: int,
+        self,
+        query_embedding: list[float],
+        q_vec: np.ndarray,
+        profile_id: str,
+        top_k: int,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         backend, self._scale_vector_backend = self._scale_vector_backend, None
         try:
             if self._vector_store and self._vector_store.available:
-                results = self._search_via_vector_store(query_embedding, q_vec, profile_id, top_k)
+                results = self._search_via_vector_store(
+                    query_embedding, q_vec, profile_id, top_k,
+                    include_global=include_global, include_shared=include_shared,
+                )
                 if results:
                     return results
-            return self._search_full_scan(query_embedding, q_vec, profile_id, top_k)
+            return self._search_full_scan(
+                query_embedding, q_vec, profile_id, top_k,
+                include_global=include_global, include_shared=include_shared,
+            )
         finally:
             self._scale_vector_backend = backend
 
@@ -213,8 +270,14 @@ class SemanticChannel:
         q_vec: np.ndarray,
         profile_id: str,
         top_k: int,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
         """KNN via VectorStore (or QAS 3-tier), then Fisher-Rao re-scoring."""
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         # V3.3.19: Try TurboQuant 3-tier search first (float32 + int8 + polar)
         if self._qas is not None:
             try:
@@ -235,12 +298,19 @@ class SemanticChannel:
                 query_embedding, top_k=top_k * 2, profile_id=profile_id,
             )
 
+        # M-01: Normalize KNN scores to [0.5, 1.0] via (score + 1.0) / 2.0 so
+        # they are on the same scale as full-scan scores computed from
+        # (_cosine_similarity(q, f) + 1.0) / 2.0 in the external_scores path.
+        # vector_store.search() clips at 0 (max(0, cosine)), which maps [–1,1]
+        # to [0,1]; the canonical formula maps to [0.5, 1.0] for positives.
+        # Both are [0,1] but different scales — without this normalization KNN
+        # scores are systematically lower and external facts always win max().
+        knn_results = [(fid, (score + 1.0) / 2.0) for fid, score in knn_results]
+
         # The vector index is partitioned by owner profile. An opted-in global
         # or authorized shared fact owned by another profile cannot enter the
         # local KNN candidate set, so merge the bounded cross-profile visible
         # supplement using the same canonical DB scope predicate as fallback.
-        include_global = bool(getattr(self, "include_global", False))
-        include_shared = bool(getattr(self, "include_shared", False))
         external_facts = self._db.get_external_visible_facts(
             profile_id,
             include_global=include_global,
@@ -272,8 +342,8 @@ class SemanticChannel:
         knn_scores = {fid: score for fid, score in knn_results}
         facts = self._db.get_facts_by_ids(
             candidate_ids, profile_id,
-            include_global=getattr(self, 'include_global', False),
-            include_shared=getattr(self, 'include_shared', False),
+            include_global=include_global,
+            include_shared=include_shared,
         )
 
         if not facts:
@@ -294,15 +364,32 @@ class SemanticChannel:
 
         scored: list[tuple[str, float]] = []
         for fact in facts:
-            cos_sim = knn_scores.get(fact.fact_id, 0.0)
+            # C2-ret H-01: recompute the final cosine from the canonical
+            # full-precision embedding using the SAME formula as the full-scan
+            # fallback, so the fast path is observationally equivalent — identical
+            # score MAGNITUDES, not merely identical rankings. The KNN/vector-store
+            # score is a candidate-SELECTION signal only (it decides which facts
+            # are Fisher-rescored), never the final magnitude; trusting it here
+            # leaked the vector store's negative-cosine clamp into public scores.
+            # When a candidate carries no usable embedding (index-only rows), fall
+            # back to the normalized KNN score, preserving the M-01 contract.
+            f_vec: np.ndarray | None = None
+            if fact.embedding is not None:
+                candidate = np.array(fact.embedding, dtype=np.float32)
+                if candidate.shape == q_vec.shape:
+                    f_vec = candidate
+
+            if f_vec is not None:
+                cos_sim = (_cosine_similarity(q_vec, f_vec) + 1.0) / 2.0
+            else:
+                cos_sim = knn_scores.get(fact.fact_id, 0.0)
 
             fisher_weight = self._fisher_weight(fact.access_count)
 
             if (fisher_weight > 0.01
                     and fact.fisher_variance is not None
-                    and fact.embedding is not None
+                    and f_vec is not None
                     and len(fact.fisher_variance) == len(q_vec)):
-                f_vec = np.array(fact.embedding, dtype=np.float32)
                 var_vec = np.array(fact.fisher_variance, dtype=np.float32)
                 f_sim = self._compute_fisher_sim(
                     q_vec, f_vec, var_vec, fact, q_mean, q_var,
@@ -323,10 +410,16 @@ class SemanticChannel:
         q_vec: np.ndarray,
         profile_id: str,
         top_k: int,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
         """Original full-table-scan search. Used as fallback when VectorStore
         is unavailable or empty (cold start).
         """
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         # Compute query Fisher params for Bayesian comparison (F45 fix)
         q_mean: np.ndarray | None = None
         q_var: np.ndarray | None = None
@@ -337,8 +430,8 @@ class SemanticChannel:
 
         facts = self._db.get_all_facts(
             profile_id,
-            include_global=getattr(self, 'include_global', False),
-            include_shared=getattr(self, 'include_shared', False),
+            include_global=include_global,
+            include_shared=include_shared,
         )
 
         scored: list[tuple[str, float]] = []

package/src/superlocalmemory/retrieval/spreading_activation.py

@@ -110,16 +110,25 @@ class SpreadingActivation:
         query: Any,
         profile_id: str = "",
         top_k: int = 7,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
         """Channel-compatible interface: (query, top_k) -> [(fact_id, score)].
 
         Matches ANNSearchable protocol (Rule 07).
+
+        Args:
+            include_global: Include global-scope facts. Falls back to the
+                instance attribute when not supplied.
+            include_shared: Include shared-scope facts. Same fallback.
         """
         if not self._config.enabled:
             return []
 
-        include_global = bool(getattr(self, "include_global", False))
-        include_shared = bool(getattr(self, "include_shared", False))
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         try:
             # Step 0: Get seed nodes from VectorStore KNN
             seed_results = self._seed_search(

package/src/superlocalmemory/retrieval/temporal_channel.py

@@ -62,7 +62,14 @@ class TemporalChannel:
     def __init__(self, db: DatabaseManager) -> None:
         self._db = db
 
-    def search(self, query: str, profile_id: str, top_k: int = 30) -> list[tuple[str, float]]:
+    def search(
+        self,
+        query: str,
+        profile_id: str,
+        top_k: int = 30,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
+    ) -> list[tuple[str, float]]:
         """Search for temporally relevant facts.
 
         Two strategies:
@@ -72,7 +79,17 @@ class TemporalChannel:
 
         Returns empty only when query has no temporal signal AND no
         entity-temporal matches.
+
+        Args:
+            include_global: Include global-scope facts. Falls back to the
+                instance attribute when not supplied.
+            include_shared: Include shared-scope facts. Same fallback.
         """
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
+
         parser = TemporalParser()
         dates = parser.extract_dates_from_text(query)
         query_dt = _parse_iso(dates.get("referenced_date"))
@@ -81,13 +98,18 @@ class TemporalChannel:
 
         # Strategy 1: Entity-temporal metadata search
         # "When did Alice...?" → find all temporal events for Alice
-        entity_results = self._entity_temporal_search(query, profile_id)
+        entity_results = self._entity_temporal_search(
+            query, profile_id,
+            include_global=include_global, include_shared=include_shared,
+        )
 
         # Strategy 2: Date proximity search
         if query_dt is None and not entity_results:
             return []
 
-        events = self._load_events(profile_id)
+        events = self._load_events(
+            profile_id, include_global=include_global, include_shared=include_shared,
+        )
         scored: dict[str, float] = {}
 
         # Include entity-temporal results with high base score
@@ -124,13 +146,21 @@ class TemporalChannel:
         return results[:top_k]
 
     def _entity_temporal_search(
-        self, query: str, profile_id: str,
+        self,
+        query: str,
+        profile_id: str,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
         """Metadata-first: find temporal events for entities mentioned in query.
 
         "When did Alice do X?" → SQL filter by entity_id for Alice → return
         all temporal facts about Alice. High precision for entity+time queries.
         """
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         import re
         _PROPER_RE = re.compile(r"\b([A-Z][a-z]+)\b")
         names = [m.group(1) for m in _PROPER_RE.finditer(query)]
@@ -151,8 +181,8 @@ class TemporalChannel:
         seen: set[str] = set()
         where, params = _scope_where(
             profile_id,
-            include_global=bool(getattr(self, "include_global", False)),
-            include_shared=bool(getattr(self, "include_shared", False)),
+            include_global=include_global,
+            include_shared=include_shared,
             prefix="af",
         )
 
@@ -179,11 +209,20 @@ class TemporalChannel:
 
         return results
 
-    def _load_events(self, profile_id: str) -> list[dict]:
+    def _load_events(
+        self,
+        profile_id: str,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
+    ) -> list[dict]:
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         where, params = _scope_where(
             profile_id,
-            include_global=bool(getattr(self, "include_global", False)),
-            include_shared=bool(getattr(self, "include_shared", False)),
+            include_global=include_global,
+            include_shared=include_shared,
             prefix="af",
         )
         rows = self._db.execute(

package/src/superlocalmemory/retrieval/temporal_frame.py

@@ -0,0 +1,102 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Temporal-context injection helpers (Phase 4, T-inject).
+
+LLMs have no innate sense of time — a recalled fact reads the same whether it
+was stored an hour ago or two years ago. These pure helpers give every recalled
+memory a human-relative age label and give the whole result set a "temporal
+frame" header anchoring it to *now*, so the model can weigh recency and treat
+aged facts as possibly stale.
+
+Reuses ``time_window.parse_timestamp`` for tolerant timestamp parsing (SQLite
+space form, ISO ``T``/``Z``, date-only) — comparisons are always on parsed
+datetimes, never strings.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: AGPL-3.0-or-later
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Iterable
+
+from superlocalmemory.retrieval.time_window import parse_timestamp
+
+__all__ = ["relative_age", "temporal_frame"]
+
+
+def _plural(n: int, unit: str) -> str:
+    return f"{n} {unit}" + ("" if n == 1 else "s")
+
+
+def relative_age(timestamp: str | None, now: datetime | None = None) -> str:
+    """Human-relative age of ``timestamp`` vs now, e.g. "3 days ago".
+
+    Returns "" when the timestamp is missing/unparseable. Future timestamps
+    (e.g. a referenced event date ahead of now) read as "in N …".
+    """
+    dt = parse_timestamp(timestamp)
+    if dt is None:
+        return ""
+    _now = now or datetime.now(timezone.utc)
+    if _now.tzinfo is None:
+        _now = _now.replace(tzinfo=timezone.utc)
+    secs = (_now - dt).total_seconds()
+    future = secs < 0
+    secs = abs(secs)
+
+    if secs < 45:
+        return "just now"
+    minutes = secs / 60.0
+    hours = minutes / 60.0
+    days = hours / 24.0
+    if minutes < 45:
+        phrase = _plural(round(minutes), "minute")
+    elif hours < 24:
+        phrase = _plural(round(hours), "hour")
+    elif days < 14:
+        phrase = _plural(round(days), "day")
+    elif days < 60:
+        phrase = _plural(round(days / 7.0), "week")
+    elif days < 365:
+        phrase = _plural(round(days / 30.0), "month")
+    else:
+        phrase = _plural(round(days / 365.0), "year")
+    return f"in {phrase}" if future else f"{phrase} ago"
+
+
+def temporal_frame(
+    timestamps: Iterable[str | None],
+    now: datetime | None = None,
+) -> str:
+    """A one-line "now" anchor + age span for a set of recalled timestamps.
+
+    Example: ``"Now: 2026-07-22T12:00:00+00:00. Recalled memories span 2 years
+    ago → just now. Treat undated or aged facts as possibly stale."``
+
+    With no dated timestamps, returns just the now-anchor + an undated note.
+    """
+    _now = now or datetime.now(timezone.utc)
+    if _now.tzinfo is None:
+        _now = _now.replace(tzinfo=timezone.utc)
+    now_iso = _now.replace(microsecond=0).isoformat()
+
+    dts = [d for d in (parse_timestamp(t) for t in timestamps) if d is not None]
+    if not dts:
+        return f"Now: {now_iso}. Recalled memories are undated."
+
+    oldest = min(dts)
+    newest = max(dts)
+    span = (
+        relative_age(oldest.isoformat(), _now)
+        if oldest == newest
+        else f"{relative_age(oldest.isoformat(), _now)} → "
+             f"{relative_age(newest.isoformat(), _now)}"
+    )
+    return (
+        f"Now: {now_iso}. Recalled memories span {span}. "
+        f"Treat undated or aged facts as possibly stale."
+    )

package/src/superlocalmemory/retrieval/temporal_validity_filter.py

@@ -0,0 +1,135 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Bi-temporal validity filter for the retrieval pipeline (Phase 4, T1).
+
+Post-retrieval filter for *system-invalidated* facts — a fact whose temporal
+record has ``system_expired_at`` set was superseded/contradicted by a newer
+fact (see ``invalidate_fact_temporal`` / conflict-resolution supersession).
+
+P5-INT-01 (non-destructive supersession): such a fact is DEMOTED, not hidden.
+Its per-channel score is multiplied by ``superseded_demotion_factor`` (default
+0.25) and the channel lists are re-sorted, so currently-valid facts rank above
+it — but nothing valid silently vanishes. This is the Mem0-2026 design that
+wins long-term-memory benchmarks: keep every fact recallable and let
+retrieval-time recency resolve conflicts, rather than destructively deleting on
+a write-time contradiction guess (which over-fires: two complementary facts
+about the same entity diverge past the coboundary threshold and one would be
+wrongly hidden). A factor of 0.0 restores the legacy hide behaviour (a demoted
+score of 0 is gated out by the evidence floor).
+
+The filter runs on the per-channel candidate dict BEFORE RRF fusion, so fused
+ranks reflect the demotion. It queries validity only for the bounded candidate
+set (never the full ``get_valid_facts`` set) — an indexed, O(candidates) lookup
+on the hot path, no full-table scan.
+
+Pure SQL, no LLM → safe in every mode including Mode A. A no-op when nothing is
+invalidated and when config.enabled is False.
+
+Integrates with ChannelRegistry.register_filter() using the FilterFn signature:
+    (all_channel_results, profile_id, context) -> filtered_results
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: AGPL-3.0-or-later
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from superlocalmemory.core.config import TemporalValidatorConfig
+    from superlocalmemory.retrieval.channel_registry import ChannelRegistry
+    from superlocalmemory.storage.database import DatabaseManager
+
+logger = logging.getLogger(__name__)
+
+
+class TemporalValidityFilter:
+    """Demotes system-invalidated (superseded) facts in retrieval candidates."""
+
+    __slots__ = ("_db", "_demotion_factor")
+
+    def __init__(self, db: DatabaseManager, demotion_factor: float = 0.25) -> None:
+        self._db = db
+        # Clamp to [0, 1]. 0.0 = legacy hide (evidence floor drops zero-score
+        # facts); 1.0 = no demotion.
+        self._demotion_factor = max(0.0, min(1.0, float(demotion_factor)))
+
+    def filter(
+        self,
+        all_results: dict[str, list[tuple[str, float]]],
+        profile_id: str,
+        context: Any,
+    ) -> dict[str, list[tuple[str, float]]]:
+        """Demote superseded fact_ids in every channel's candidate list.
+
+        Matches FilterFn signature from channel_registry.py.
+
+        Args:
+            all_results: Channel name -> [(fact_id, score)] dict.
+            profile_id: Current profile.
+            context: Optional context (unused).
+
+        Returns:
+            A new dict where system-invalidated facts keep their channel
+            presence but have their score scaled by the demotion factor and the
+            channel lists re-sorted (so valid facts rank above them). Inputs are
+            never mutated (immutability). Unchanged when nothing is invalidated.
+        """
+        # Collect all unique candidate fact_ids across every channel.
+        all_fact_ids: set[str] = set()
+        for channel_results in all_results.values():
+            for fact_id, _ in channel_results:
+                all_fact_ids.add(fact_id)
+
+        if not all_fact_ids:
+            return all_results
+
+        try:
+            invalid = self._db.get_invalidated_fact_ids(
+                list(all_fact_ids), profile_id,
+            )
+        except Exception as exc:
+            # Fail-open: a validity-lookup error must never break retrieval.
+            logger.warning("Temporal validity lookup failed: %s", exc)
+            return all_results
+
+        if not invalid:
+            return all_results
+
+        factor = self._demotion_factor
+        demoted: dict[str, list[tuple[str, float]]] = {}
+        for channel_name, channel_results in all_results.items():
+            new_list = [
+                (fact_id, score * factor if fact_id in invalid else score)
+                for fact_id, score in channel_results
+            ]
+            # Re-sort descending so demoted (superseded) facts fall below
+            # currently-valid facts in this channel's rank order.
+            new_list.sort(key=lambda pair: pair[1], reverse=True)
+            demoted[channel_name] = new_list
+        return demoted
+
+
+def register_temporal_validity_filter(
+    registry: ChannelRegistry,
+    db: DatabaseManager,
+    config: TemporalValidatorConfig,
+) -> None:
+    """Register the bi-temporal validity filter into the channel registry.
+
+    Does nothing if config.enabled is False.
+
+    Args:
+        registry: Channel registry to register with.
+        db: Database manager for validity queries.
+        config: Temporal-validator configuration.
+    """
+    if not getattr(config, "enabled", True):
+        return
+    factor = getattr(config, "superseded_demotion_factor", 0.25)
+    f = TemporalValidityFilter(db, demotion_factor=factor)
+    registry.register_filter(f.filter)