superlocalmemory 4.1.6 → 4.1.8

package/src/superlocalmemory/learning/engagement_features.py

@@ -0,0 +1,279 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Engagement observed from what an agent did, not from what it was asked to say.
+
+WHY THIS EXISTS
+---------------
+The reward ladder in ``reward_proxy`` asks one question — did a recalled
+``fact_id`` appear verbatim in a later tool event — and defaults to ``0.5`` when
+the answer is no. Both halves of that are broken.
+
+The question requires the caller to copy an opaque marker into its next tool
+call. Nothing makes it: no tool description asks for it and no rule requires
+it. A design that depends on a behaviour nothing produces has no signal, and
+in practice no signal was ever registered.
+
+The default is worse than no answer. ``alpha += 0.5`` and ``beta += 0.5`` move
+together, so a Beta posterior keeps its mean at exactly 0.5 while its variance
+*shrinks*. Every neutral settlement makes an arm more confident that it is
+average and harder for real evidence to move later. Neutral is not a safe
+default; it is a slow commitment to knowing nothing.
+
+WHAT REPLACES IT
+----------------
+Features computed from rows the system already writes. An agent that uses a
+recalled memory leaves traces whether or not it cooperates: it reads or edits
+the files the memory names, its next actions stay on the memory's subject, it
+writes a follow-up memory that overlaps. None of that requires it to quote an
+identifier.
+
+Every feature here is observable, and each is reported separately so a reward
+can say *why*. When nothing is observable the answer is ``None`` — abstain —
+never a number.
+
+NOT SELF-REFERENTIAL
+--------------------
+A signal derived from the mechanism it evaluates cannot detect that mechanism's
+failure. Ranking position is therefore not a feature: the bandit chose the
+ranking, so scoring it by what the bandit ranked first would confirm the bandit
+to itself. Position enters only in ``propensity.py``, as a correction applied
+*against* the observation, never as evidence for it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+
+__all__ = [
+    "EngagementFeatures",
+    "OBSERVATION_WINDOW_SEC",
+    "extract_features",
+    "tokenize",
+]
+
+#: How long after a recall an action may still be counted as caused by it.
+#: Wider than the old 30 s hit window: an agent reads a memory, then thinks,
+#: then acts, and 30 s discarded most of the acting.
+OBSERVATION_WINDOW_SEC = 300
+
+#: Tools whose payload naming a recalled memory's content is strong evidence
+#: the memory was actually used, not merely returned.
+_ARTIFACT_TOOLS = frozenset({"Write", "Edit", "NotebookEdit", "MultiEdit"})
+
+#: Words carrying no topical signal; overlap on these is noise, and without
+#: this filter every pair of payloads overlaps.
+_STOPWORDS = frozenset("""
+a an the and or but if then than that this these those is are was were be been
+being to of in on at by for with from as it its into over under about after
+before not no nor so such can will would should could may might must do does
+did done have has had i you he she we they them his her their our your my me
+""".split())
+
+_TOKEN_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_.\-/]{2,}")
+
+
+def tokenize(text: str) -> set[str]:
+    """Content-bearing lowercase tokens, stopwords and short words removed."""
+    if not text:
+        return set()
+    return {
+        tok for tok in (m.group(0).lower() for m in _TOKEN_RE.finditer(text))
+        if tok not in _STOPWORDS and len(tok) > 2
+    }
+
+
+@dataclass
+class EngagementFeatures:
+    """What was observed after one recall. Every field is measured, not inferred.
+
+    ``observed`` is the honest summary: False means nothing happened that this
+    module can see, which is a reason to abstain rather than a reason to
+    penalise. An agent may have used a memory perfectly and left no trace.
+    """
+
+    #: Best Jaccard-style overlap between any recalled fact and any following
+    #: tool payload, in [0, 1].
+    peak_overlap: float = 0.0
+    #: Overlap restricted to file-writing tools — the memory reached an artifact.
+    artifact_overlap: float = 0.0
+    #: A later remember/update_memory overlapping a recalled fact.
+    followup_write_overlap: float = 0.0
+    #: The same question asked again inside the requery window: the answer did
+    #: not satisfy. The one unambiguous negative available.
+    requeried: bool = False
+    #: Seconds from recall to the first following action, when there was one.
+    dwell_sec: float | None = None
+    #: Tool events seen in the window at all.
+    action_count: int = 0
+    #: Which fact ids the overlap landed on, so a reward can be explained.
+    matched_fact_ids: list[str] = field(default_factory=list)
+    #: A recalled fact's own id appeared verbatim in a later tool event. Rare,
+    #: because nothing makes an agent echo it — but unambiguous when it does
+    #: happen, so it is kept as the strongest single piece of evidence rather
+    #: than discarded along with the ladder that relied on it alone.
+    marker_hit: bool = False
+
+    @property
+    def observed(self) -> bool:
+        """Whether anything at all was seen. Drives abstention."""
+        return bool(
+            self.requeried
+            or self.marker_hit
+            or self.action_count > 0
+            and (
+                self.peak_overlap > 0.0
+                or self.artifact_overlap > 0.0
+                or self.followup_write_overlap > 0.0
+            )
+        )
+
+
+def _table_exists(conn: sqlite3.Connection, name: str) -> bool:
+    try:
+        return conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (name,),
+        ).fetchone() is not None
+    except sqlite3.Error:
+        return False
+
+
+def _fact_tokens(conn: sqlite3.Connection, fact_ids: list[str]) -> dict[str, set[str]]:
+    """Content tokens per fact. Entities are folded in when the column exists,
+    because a memory's entities are what a later action is most likely to name.
+    """
+    if not fact_ids or not _table_exists(conn, "atomic_facts"):
+        return {}
+    placeholders = ",".join("?" * len(fact_ids))
+    try:
+        rows = conn.execute(
+            f"SELECT fact_id, content, COALESCE(entities_json,'') "  # noqa: S608
+            f"FROM atomic_facts WHERE fact_id IN ({placeholders})",
+            tuple(fact_ids),
+        ).fetchall()
+    except sqlite3.Error:
+        return {}
+
+    out: dict[str, set[str]] = {}
+    for fact_id, content, entities_json in rows:
+        tokens = tokenize(content or "")
+        if entities_json:
+            try:
+                parsed = json.loads(entities_json)
+            except (ValueError, TypeError):
+                parsed = None
+            if isinstance(parsed, list):
+                for ent in parsed:
+                    tokens |= tokenize(ent if isinstance(ent, str) else str(ent))
+        if tokens:
+            out[str(fact_id)] = tokens
+    return out
+
+
+def _following_events(
+    conn: sqlite3.Connection,
+    session_id: str,
+    profile_id: str,
+    recalled_at: datetime,
+) -> list[tuple[str, str]]:
+    """(tool_name, payload) for actions in this conversation after the recall.
+
+    Scoped to the conversation. Without that predicate a busy machine's
+    unrelated activity in the same five minutes would read as engagement.
+    """
+    if not _table_exists(conn, "tool_events"):
+        return []
+    start = recalled_at.isoformat()
+    end = (recalled_at + timedelta(seconds=OBSERVATION_WINDOW_SEC)).isoformat()
+    try:
+        cols = {r[1] for r in conn.execute("PRAGMA table_info(tool_events)")}
+    except sqlite3.Error:
+        return []
+    if not {"session_id", "created_at", "tool_name"} <= cols:
+        return []
+
+    sql = (
+        "SELECT tool_name, COALESCE(input_summary,'') || ' ' || "
+        "COALESCE(output_summary,'') FROM tool_events "
+        "WHERE session_id = ? AND created_at > ? AND created_at <= ?"
+    )
+    params: tuple = (session_id, start, end)
+    if "profile_id" in cols:
+        sql += " AND (profile_id = ? OR profile_id IS NULL)"
+        params += (profile_id,)
+    sql += " ORDER BY created_at LIMIT 200"
+    try:
+        return [(str(r[0]), str(r[1])) for r in conn.execute(sql, params)]
+    except sqlite3.Error:
+        return []
+
+
+#: A single word in common is coincidence, not evidence. Any two texts about
+#: software share one token eventually, and containment makes that worse: a
+#: memory that reduces to one content word scores a perfect 1.0 against every
+#: payload containing it. Two independent tokens is the cheapest threshold that
+#: distinguishes a shared subject from a shared word.
+_MIN_OVERLAP_TOKENS = 2
+
+
+def _overlap(fact_tokens: set[str], payload_tokens: set[str]) -> float:
+    """Containment of the memory in the action, not symmetric Jaccard.
+
+    A tool payload is often far larger than a fact, and Jaccard would divide
+    that signal away precisely when the evidence is strongest.
+    """
+    if not fact_tokens or not payload_tokens:
+        return 0.0
+    shared = fact_tokens & payload_tokens
+    if len(shared) < _MIN_OVERLAP_TOKENS:
+        return 0.0
+    return len(shared) / len(fact_tokens)
+
+
+def extract_features(
+    memory_conn: sqlite3.Connection,
+    *,
+    session_id: str,
+    profile_id: str,
+    fact_ids: list[str],
+    recalled_at: datetime,
+    requeried: bool = False,
+    marker_hit: bool = False,
+) -> EngagementFeatures:
+    """Observe what followed one recall. Never raises; returns empty on error."""
+    features = EngagementFeatures(
+        requeried=bool(requeried), marker_hit=bool(marker_hit),
+    )
+    try:
+        by_fact = _fact_tokens(memory_conn, [str(f) for f in fact_ids])
+        events = _following_events(memory_conn, session_id, profile_id, recalled_at)
+    except sqlite3.Error:
+        return features
+
+    features.action_count = len(events)
+    if not by_fact or not events:
+        return features
+
+    matched: set[str] = set()
+    for tool_name, payload in events:
+        payload_tokens = tokenize(payload)
+        if not payload_tokens:
+            continue
+        for fact_id, tokens in by_fact.items():
+            score = _overlap(tokens, payload_tokens)
+            if score <= 0.0:
+                continue
+            matched.add(fact_id)
+            features.peak_overlap = max(features.peak_overlap, score)
+            if tool_name in _ARTIFACT_TOOLS:
+                features.artifact_overlap = max(features.artifact_overlap, score)
+            if tool_name.endswith(("remember", "update_memory")):
+                features.followup_write_overlap = max(
+                    features.followup_write_overlap, score,
+                )
+    features.matched_fact_ids = sorted(matched)
+    return features

package/src/superlocalmemory/learning/outcome_queue.py

@@ -26,6 +26,8 @@ by ``unified_daemon.py``'s lifespan hook.
 
 from __future__ import annotations
 
+
+from superlocalmemory.core.session_identity import is_conversation
 import logging
 import queue
 import threading
@@ -112,6 +114,18 @@ def enqueue_recall(event: RecallEvent) -> None:
         # If the caller can't name a session, we silently drop: this
         # is a recall whose outcome cannot match to a signal anyway.
         return
+    if not is_conversation(event.session_id, event.profile_id):
+        # Same reason, one step further. A front that invents an id names
+        # itself, not a caller: ``engine:<pid>`` is the daemon every client
+        # shares, ``cli:<pid>`` a process that exits before any follow-on
+        # action, ``http:<ms>`` a single request. No tool event can ever
+        # carry one, so the outcome is unmatchable the moment it is written.
+        # Recording it anyway is not free: a play that is never settled from
+        # evidence is eventually settled from nothing, and a neutral update
+        # tightens a Beta posterior around its prior instead of leaving it
+        # movable.
+        _bump("recall_dropped_synthetic_session")
+        return
     try:
         _queue.put_nowait(event)
         _bump("recall_enqueued")

package/src/superlocalmemory/learning/propensity.py

@@ -0,0 +1,131 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Inverse-propensity weighting, so the bandit cannot confirm itself.
+
+THE BIAS
+--------
+The bandit decides what is shown, and engagement is then measured on what was
+shown. Feed that back raw and the loop is circular: an arm ranked first is seen
+more, so it is engaged with more, so it is ranked first more. The arm that wins
+is the one that was already winning, and the posterior records popularity it
+manufactured rather than usefulness it discovered.
+
+That is the self-referential signal in its exact form — a measurement taken
+through the mechanism it is meant to evaluate cannot see that mechanism fail.
+
+THE CORRECTION
+--------------
+Weight each observation by the inverse of the probability the policy had of
+showing that arm. An arm the policy was unlikely to show, that was engaged with
+anyway, is strong evidence; an arm the policy shows almost always is weak
+evidence whatever happens to it. This is the standard IPS estimator from
+counterfactual learning-to-rank, and it makes the update unbiased with respect
+to the policy's own choices.
+
+Under Thompson sampling the propensity is not a stored number: an arm is shown
+when its posterior draw beats every competitor's, so the probability is
+``P(theta_i > theta_j for all j != i)`` with each ``theta ~ Beta(alpha, beta)``.
+There is no closed form for more than two arms, so it is estimated by sampling.
+
+WHEN THE COMPETITORS ARE UNKNOWN
+--------------------------------
+Return a weight of exactly 1.0 — no correction. A wrong correction is worse
+than none: it would silently scale evidence by a number with no meaning, and
+unlike an absent correction nothing downstream could tell. Abstaining from a
+correction is visible in ``PropensityEstimate.corrected``.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+__all__ = ["PropensityEstimate", "estimate_propensity", "ips_weight", "MAX_WEIGHT"]
+
+#: Ceiling on the weight a single observation may carry. IPS has unbounded
+#: variance as propensity approaches zero: one rare event with p = 0.001 would
+#: otherwise move a posterior by 1000 plays' worth. Clipping trades a little
+#: bias for a variance that does not destroy the estimate — the standard
+#: bias-variance trade in clipped IPS.
+MAX_WEIGHT = 10.0
+
+#: Propensities below this are treated as this value before inversion.
+_MIN_PROPENSITY = 1.0 / MAX_WEIGHT
+
+#: Monte Carlo draws. 2000 puts the standard error of a mid-range propensity
+#: near 0.01, which is finer than the weight clipping can express.
+_DRAWS = 2000
+
+
+@dataclass(frozen=True)
+class PropensityEstimate:
+    """A propensity and whether it was actually derived from anything."""
+
+    propensity: float
+    weight: float
+    corrected: bool
+    competitors: int = 0
+
+
+def estimate_propensity(
+    arm: tuple[float, float],
+    competitors: list[tuple[float, float]],
+    *,
+    draws: int = _DRAWS,
+    rng: random.Random | None = None,
+) -> float:
+    """P(this arm's Thompson draw is the largest), by Monte Carlo.
+
+    ``arm`` and each competitor are ``(alpha, beta)`` posteriors.  With no
+    competitors the arm is shown whenever it is considered, so the propensity
+    is 1.0 and the correction is a no-op.
+    """
+    if not competitors:
+        return 1.0
+    # Fixed seed by default: the same play settled twice must produce the
+    # same weight, or a retry would move a posterior differently than the
+    # first attempt did.
+    generator = rng or random.Random(20260824)
+    alpha, beta = _sane(arm)
+    others = [_sane(c) for c in competitors]
+
+    wins = 0
+    for _ in range(max(1, int(draws))):
+        mine = generator.betavariate(alpha, beta)
+        if all(mine > generator.betavariate(a, b) for a, b in others):
+            wins += 1
+    return wins / max(1, int(draws))
+
+
+def _sane(posterior: tuple[float, float]) -> tuple[float, float]:
+    """Beta requires strictly positive parameters; a stored 0 would raise."""
+    alpha, beta = posterior
+    return (max(float(alpha), 1e-6), max(float(beta), 1e-6))
+
+
+def ips_weight(
+    arm: tuple[float, float] | None,
+    competitors: list[tuple[float, float]] | None,
+    *,
+    draws: int = _DRAWS,
+    rng: random.Random | None = None,
+) -> PropensityEstimate:
+    """Clipped inverse-propensity weight for one observation.
+
+    Returns ``corrected=False`` and ``weight=1.0`` when there is nothing to
+    correct against, so a caller can tell an uncorrected update from a
+    corrected one that happened to land on 1.0.
+    """
+    if arm is None or not competitors:
+        return PropensityEstimate(propensity=1.0, weight=1.0, corrected=False)
+
+    propensity = estimate_propensity(arm, competitors, draws=draws, rng=rng)
+    clipped = max(propensity, _MIN_PROPENSITY)
+    weight = min(1.0 / clipped, MAX_WEIGHT)
+    return PropensityEstimate(
+        propensity=propensity,
+        weight=weight,
+        corrected=True,
+        competitors=len(competitors),
+    )

package/src/superlocalmemory/learning/reward.py

@@ -735,6 +735,20 @@ class EngagementRewardModel:
                 signals = json.loads(row["signals_json"] or "{}")
             except json.JSONDecodeError:  # pragma: no cover
                 signals = {}
+            # A row that accumulated no signal has nothing to say. It used to
+            # be written out as an outcome anyway, carrying the label
+            # formula's base term of exactly 0.5 and marked ``settled`` as
+            # though a judgement had been reported. That value is not a
+            # harmless placeholder: ``alpha += 0.5`` with ``beta += 0.5`` moves
+            # both sides together, so the posterior keeps its mean and loses
+            # spread, and an arm settled this way repeatedly never leaves its
+            # prior.
+            #
+            # The row is still finalized, so it stops being rescanned; it is
+            # simply not turned into evidence it never was.
+            if not signals:
+                settle_ids.append(row["outcome_id"])
+                continue
             reward = _compute_label(signals)
             insert_batch.append(
                 (
@@ -756,7 +770,11 @@ class EngagementRewardModel:
         _CHUNK = 500
         written = 0
         try:
-            for i in range(0, len(insert_batch), _CHUNK):
+            # insert_batch and settle_ids are no longer parallel: a row with
+            # no signals is finalized without producing an outcome. Pad the
+            # insert side so each burst still pairs a write with the right
+            # finalizations, and never index one by the other's length.
+            for i in range(0, max(len(insert_batch), len(settle_ids)), _CHUNK):
                 i_chunk = insert_batch[i:i + _CHUNK]
                 s_chunk = settle_ids[i:i + _CHUNK]
                 placeholders = ",".join("?" * len(s_chunk))
@@ -764,22 +782,30 @@ class EngagementRewardModel:
                     conn = self._get_conn()
                     conn.execute("BEGIN IMMEDIATE")
                     try:
-                        conn.executemany(
-                            "INSERT OR REPLACE INTO action_outcomes "
-                            "(outcome_id, profile_id, query, fact_ids_json,"
-                            " outcome, context_json, timestamp, reward,"
-                            " settled, settled_at, recall_query_id) "
-                            "VALUES "
-                            "(?, ?, '', ?, 'settled', '{}', ?, ?, 1, ?, ?)",
-                            i_chunk,
-                        )
-                        conn.execute(
-                            "UPDATE pending_outcomes "
-                            f"SET status = 'settled' WHERE outcome_id IN ({placeholders})",
-                            s_chunk,
-                        )
+                        if i_chunk:
+                            conn.executemany(
+                                "INSERT OR REPLACE INTO action_outcomes "
+                                "(outcome_id, profile_id, query, fact_ids_json,"
+                                " outcome, context_json, timestamp, reward,"
+                                " settled, settled_at, recall_query_id) "
+                                "VALUES "
+                                "(?, ?, '', ?, 'settled', '{}', ?, ?, 1, ?, ?)",
+                                i_chunk,
+                            )
+                        if s_chunk:
+                            conn.execute(
+                                "UPDATE pending_outcomes "
+                                f"SET status = 'settled' "
+                                f"WHERE outcome_id IN ({placeholders})",
+                                s_chunk,
+                            )
                         conn.execute("COMMIT")
-                        written += len(i_chunk)
+                        # Count what was FINALIZED, not what was written. A row
+                        # with no signals is finalized without producing an
+                        # outcome, and callers use this number to know the
+                        # backlog drained — counting inserts would report 0
+                        # forever and make the reaper look dead.
+                        written += len(s_chunk)
                     except sqlite3.Error:
                         conn.execute("ROLLBACK")
                         raise

package/src/superlocalmemory/learning/reward_model.py

@@ -0,0 +1,144 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Turn observed engagement into a reward, or into an honest refusal.
+
+ABSTENTION IS THE POINT
+-----------------------
+The ladder this replaces always produced a number. When it saw nothing it
+produced ``0.5``, and ``0.5`` is not neutral: ``alpha += 0.5`` with
+``beta += 0.5`` holds a Beta posterior's mean at exactly 0.5 while shrinking
+its variance, so each empty settlement makes an arm *more certain* it is
+average and *less* movable by the evidence that finally arrives. Applied often
+enough it does not merely fail to learn — it commits, with growing confidence,
+to knowing nothing.
+
+So this module returns ``None`` when nothing was observed. An unobserved recall
+leaves the posterior untouched and free. Absence of evidence is recorded as
+absence of evidence.
+
+THE SCALE
+---------
+Positive evidence maps into ``(0.5, 1.0]``, a requery to ``0.0``, and nothing to
+``None``. Nothing maps *to* 0.5, because that value is reserved for "no
+information" and no observation carries that meaning: if it was worth
+observing it was worth moving the posterior.
+
+Weights are module constants and deliberately legible rather than fitted. There
+is no ground-truth corpus of "was this memory actually useful" to fit against,
+and inventing one from the system's own rankings would be the circularity
+``propensity.py`` exists to break. They are a documented prior over evidence
+strength; the *learning* happens in the posterior these rewards update, not in
+the constants.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from superlocalmemory.learning.engagement_features import EngagementFeatures
+
+__all__ = ["RewardDecision", "score", "REQUERY_REWARD"]
+
+#: A question asked again is the one unambiguous statement that an answer did
+#: not serve. It is the only hard zero available.
+REQUERY_REWARD = 0.0
+
+#: Evidence weights, strongest first.
+#:  - a memory whose content reaches a written artifact was used, not just read
+#:  - a follow-up memory overlapping it means the agent built on it
+#:  - appearing in any later action is real but weaker: the agent may have been
+#:    working on the subject regardless of what was recalled
+_W_ARTIFACT = 0.50
+_W_FOLLOWUP = 0.30
+_W_PRESENCE = 0.20
+
+#: Positive evidence starts just above the reserved no-information value, so
+#: the weakest real observation still moves an arm up rather than nowhere.
+_POSITIVE_FLOOR = 0.55
+
+
+@dataclass(frozen=True)
+class RewardDecision:
+    """A reward, or an abstention, with the reason attached.
+
+    ``reward is None`` means do not update. ``kind`` names what was seen so a
+    settled play can be explained after the fact instead of being a bare float.
+    """
+
+    reward: float | None
+    kind: str
+    detail: str = ""
+
+    @property
+    def abstained(self) -> bool:
+        return self.reward is None
+
+
+def score(features: EngagementFeatures) -> RewardDecision:
+    """Map observations to a reward in [0, 1], or abstain.
+
+    Never raises: a settler running over a month of rows must not stop on one
+    malformed observation.
+    """
+    if features.marker_hit:
+        # The agent named the memory outright. Nothing makes it do this, so it
+        # is rare, but when it happens there is nothing to infer.
+        return RewardDecision(
+            reward=1.0,
+            kind="proxy_position",
+            detail="a recalled fact id appeared in a later tool event",
+        )
+
+    if features.requeried:
+        return RewardDecision(
+            reward=REQUERY_REWARD,
+            kind="proxy_requery",
+            detail="the same question was asked again inside the window",
+        )
+
+    if not features.observed:
+        return RewardDecision(
+            reward=None,
+            kind="unobserved",
+            detail=(
+                f"no engagement visible in {features.action_count} following "
+                "action(s); posterior left untouched"
+            ),
+        )
+
+    artifact = _clamp(features.artifact_overlap)
+    followup = _clamp(features.followup_write_overlap)
+    presence = _clamp(features.peak_overlap)
+
+    strength = (
+        _W_ARTIFACT * artifact
+        + _W_FOLLOWUP * followup
+        + _W_PRESENCE * presence
+    )
+    # strength in [0, 1]; map onto (floor, 1.0].
+    reward = _POSITIVE_FLOOR + (1.0 - _POSITIVE_FLOOR) * _clamp(strength)
+
+    if artifact > 0.0:
+        kind = "artifact_overlap"
+    elif followup > 0.0:
+        kind = "followup_overlap"
+    else:
+        kind = "presence_overlap"
+
+    return RewardDecision(
+        reward=round(reward, 6),
+        kind=kind,
+        detail=(
+            f"artifact={artifact:.3f} followup={followup:.3f} "
+            f"presence={presence:.3f} on {len(features.matched_fact_ids)} fact(s)"
+        ),
+    )
+
+
+def _clamp(value: float) -> float:
+    try:
+        v = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+    return 0.0 if v < 0.0 else (1.0 if v > 1.0 else v)