dsh-biocore 0.3.3 → 0.5.0

package/python/biocore_memory/scoring.py

@@ -0,0 +1,203 @@
+# -*- coding: utf-8 -*-
+"""task-AstrBot-migration-1: pure memory scoring math moved out of main.py.
+
+Behavior-preserving extraction of four host helpers:
+  memory_importance(core, role)
+  score_parts(core, entry, cosine, ...)
+  memory_score(core, entry, cosine, ...)
+  select_overflow_archive(entries, room, importance_max=0.5)
+
+The host keeps thin wrappers that pass its own switches (salience/fan) and the
+ACT_R_DECAY constant, so identical inputs give identical numbers.
+"""
+from __future__ import annotations
+
+import math
+import time
+
+try:  # package context (AstrBot plugin)
+    from .. import memory_meta
+except Exception:  # pragma: no cover - flat checkout
+    import memory_meta  # type: ignore
+
+ACT_R_DECAY_DEFAULT = 0.5
+DEFAULT_COSINE = 0.0
+
+
+def _num(value, default=0.0):
+    try:
+        number = float(value)
+    except Exception:
+        return default
+    return number if number == number else default
+
+
+def memory_importance(core, role):
+    """Legacy importance heuristic; core None -> 0.5."""
+    if core is None:
+        return 0.5
+    salience = (0.25 + 0.35 * float(getattr(core, "a", 0.5))
+                + 0.25 * abs(float(getattr(core, "v", 0.0))))
+    salience += 0.15 * (1.0 - float(getattr(core, "trust", 0.5)))
+    if role == "assistant":
+        salience *= 0.9
+    return max(0.15, min(1.0, salience))
+
+
+def score_parts(core, entry, cosine, query_text="", hybrid=False,
+                sensitive_protect=False, *, salience_boost=False,
+                fan_penalty=False, fan_cap=32, fan_floor=0.70, fan_gain=0.10,
+                act_r_decay=ACT_R_DECAY_DEFAULT, now=None):
+    """Deterministic score plus bounded component factors (same as main.py)."""
+    stamp = time.time() if now is None else float(now)
+    importance = memory_meta.effective_importance(entry)
+    age = max(0.0, stamp - float(entry.get("ts", 0) or 0))
+    age_days = age / 86400.0
+    retention_model = (getattr(core, "retention_model", "power_law")
+                       if core is not None else "power_law")
+    if retention_model in ("power_law", "multi_scale"):
+        recency = memory_meta.retention_weight(age_days, retention_model)
+    else:
+        recency = 1.0 / math.pow(1.0 + max(0.0, age_days) * 0.35, 0.55)
+    try:
+        recall_count = int(entry.get("recall_count", 0) or 0)
+    except Exception:
+        recall_count = 0
+    assoc = memory_meta.decayed_assoc(entry)
+    try:
+        due = 1.15 if 0 < float(entry.get("next_review_ts", 0) or 0) <= stamp else 1.0
+    except Exception:
+        due = 1.0
+    try:
+        stability = max(0.2, float(entry.get("stability_days", 1.0) or 1.0))
+    except Exception:
+        stability = 1.0
+    retention = math.exp(-age_days / stability)
+    try:
+        _d = act_r_decay
+        _b = math.log(max(1e-9, (age_days + 0.05) ** (-_d)))
+        base = 1.0 / (1.0 + math.exp(-(_b + 1.0)))
+    except Exception:
+        base = 0.5
+    try:
+        schema = memory_meta.effective_schema_congruence(entry)
+    except Exception:
+        schema = 0.0
+    inhibition = memory_meta.retrieval_inhibition(entry)
+    regulation = (str(getattr(core, "regulation", "none") or "none")
+                  if core is not None else "none")
+    regulation_mod = memory_meta.regulation_memory_modifier(entry, regulation)
+    lexical_mod = 1.0
+    if hybrid and query_text:
+        try:
+            entry_text = str(entry.get("text") or "")
+            variants = memory_meta.expand_query(query_text)
+            lexical = max(memory_meta.lexical_overlap(variant, entry_text)
+                          for variant in variants) if variants else 0.0
+            lexical_mod = 1.0 + 0.12 * lexical
+        except Exception:
+            lexical_mod = 1.0
+    sensitive_mod = 1.0
+    if sensitive_protect:
+        sensitive_mod = memory_meta.sensitivity_weight(entry)
+    source_weight = memory_meta.retrieval_weight(entry)
+    score = (cosine * (0.40 + 0.60 * importance) * recency
+             * (0.65 + 0.35 * retention)
+             * (0.85 + 0.15 * base)
+             * (1.0 + 0.10 * math.log1p(max(0, recall_count)))
+             * due
+             * (1.0 + 0.05 * math.log1p(max(0, assoc)))
+             * source_weight
+             * (1.0 + 0.10 * schema)
+             * (1.0 - 0.15 * inhibition)
+             * regulation_mod
+             * lexical_mod
+             * sensitive_mod)
+    sal_factor = 1.0
+    if salience_boost:
+        try:
+            _c = max(0.0, min(1.0, float(cosine)))
+            if _c > 0.0:
+                sal_factor = 0.90 + 0.20 * _c
+                score *= sal_factor
+        except Exception:
+            sal_factor = 1.0
+    if fan_penalty:
+        try:
+            links = entry.get("links") if isinstance(entry.get("links"), list) else []
+            try:
+                raw_assoc = sum(int(v) for v in (entry.get("assoc") or {}).values())
+            except Exception:
+                raw_assoc = 0
+            fan = min(int(fan_cap or 32), raw_assoc + len(links))
+            penalty = max(float(fan_floor or 0.70),
+                          1.0 / (1.0 + float(fan_gain or 0.10)
+                                 * math.log1p(max(0, fan))))
+            score *= penalty
+        except Exception:
+            pass
+    return {
+        "score": float(score),
+        "salience": round(sal_factor, 4),
+        "cosine": round(float(cosine), 6),
+        "importance": round(importance, 4),
+        "recency": round(recency, 4),
+        "retention": round(0.65 + 0.35 * retention, 4),
+        "base": round(0.85 + 0.15 * base, 4),
+        "recall_boost": round(1.0 + 0.10 * math.log1p(max(0, recall_count)), 4),
+        "assoc_boost": round(1.0 + 0.05 * math.log1p(max(0, assoc)), 4),
+        "due": round(due, 4),
+        "source_weight": round(float(source_weight), 4),
+        "schema": round(schema, 4),
+        "inhibition": round(float(inhibition), 4),
+        "regulation": round(float(regulation_mod), 4),
+        "lexical": round(float(lexical_mod), 4),
+        "sensitive": round(float(sensitive_mod), 4),
+    }
+
+
+def memory_score(core, entry, cosine, query_text="", hybrid=False,
+                 sensitive_protect=False, *, salience_boost=False,
+                 fan_penalty=False, fan_cap=32, fan_floor=0.70, fan_gain=0.10,
+                 act_r_decay=ACT_R_DECAY_DEFAULT, now=None):
+    parts = score_parts(
+        core, entry, cosine, query_text=query_text, hybrid=hybrid,
+        sensitive_protect=sensitive_protect, salience_boost=salience_boost,
+        fan_penalty=fan_penalty, fan_cap=fan_cap, fan_floor=fan_floor,
+        fan_gain=fan_gain, act_r_decay=act_r_decay, now=now)
+    score = float(parts.get("score", 0.0))
+    try:
+        trace = getattr(core, "_last_memory_trace", None) if core is not None else None
+        if isinstance(trace, dict):
+            entry_id = str(entry.get("id") or "")
+            if entry_id and entry_id in [str(x) for x in (trace.get("entry_ids") or [])]:
+                valence = max(-1.0, min(1.0, float(trace.get("valence", 0.0) or 0.0)))
+                score *= 1.0 + 0.04 * valence
+    except Exception:
+        pass
+    return max(0.0, score)
+
+
+def select_overflow_archive(entries, room, importance_max=0.5):
+    """Deterministic low-importance unpinned overflow selection."""
+    rows = [row for row in (entries or []) if isinstance(row, dict)]
+    rows.sort(key=lambda row: float(row.get("ts", 0) or 0))
+    try:
+        keep_n = max(0, int(room or 0))
+    except Exception:
+        keep_n = 80
+    keep = rows[-keep_n:] if keep_n else []
+    overflow = []
+    for row in rows:
+        if row in keep:
+            continue
+        try:
+            importance = float(row.get("importance", 0.5) or 0.5)
+        except Exception:
+            importance = 0.5
+        if importance < float(importance_max) and not memory_meta.is_pinned(row):
+            overflow.append(row)
+        else:
+            keep.append(row)
+    keep.sort(key=lambda row: float(row.get("ts", 0) or 0))
+    return keep, overflow

package/python/biocore_memory/space.py

@@ -0,0 +1,355 @@
+# -*- coding: utf-8 -*-
+"""task-244 step 1: shadow coordinates for memory entries (write-only).
+
+Every entry gets a read-only "space" dict with five axes:
+
+    semantic    the embedding vector (reused when the entry already has one)
+                with its provider / model name, plus topic / entity tags and a
+                text fingerprint fallback. semantic distance = 1 - cosine
+                (Jaccard over tags when either side has no vector)
+    time        the entry ts, its own half-life in minutes, its age
+    affect      v / a as they stood when the entry was written
+    social      scope + trust / closeness at write time
+    activation  importance / hits / retrieval_count / last_hit
+
+Boundaries
+    Step 1 only adds coordinates. recall(), ranking and the memory score never
+    read this module, and recall keeps its old behaviour byte for byte.
+    The switch spatial_recall is OFF by default; with it off nothing is written.
+    A coordinate that cannot be built returns None and the entry is untouched.
+
+    Distances are reported PER AXIS. They are never added into one number; the
+    nearest list is ordered lexicographically (semantic, affect, time,
+    activation, social), which keeps every axis visible in the ranking.
+
+Weights / half-lives below are [engineering] (see docs/PAPER-MAP.md).
+"""
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+
+SCHEMA = 1
+SWITCH_KEY = "spatial_recall"
+ENV_KEY = "BIOCORE_SPATIAL_RECALL"
+AXES = ("semantic", "time", "affect", "social", "activation")
+DISTANCE_ORDER = ("semantic", "affect", "time", "activation", "social")
+
+VECTOR_LIMIT = 768
+TOPIC_LIMIT = 8
+ENTITY_LIMIT = 8
+FINGERPRINT_CHARS = 12
+
+BASE_HALF_LIFE_MINUTES = 180.0      # [engineering]
+HALF_LIFE_BY_KIND = {"direct": 180.0, "recall": 120.0,
+                     "summary": 240.0, "reflection": 360.0}   # [engineering]
+IMPORTANCE_SPAN = 0.5               # half-life scales 0.5x .. 1.5x
+HITS_CEILING = 20.0                 # [engineering] log scale for the hits axis
+DEFAULT_IMPORTANCE = 0.5
+DEFAULT_TRUST = 0.5
+DEFAULT_CLOSENESS = 0.5
+
+_TOKEN = re.compile(r"[a-z0-9_]+")       # latin words
+_CJK_RUN = re.compile(r"[\u4e00-\u9fff]+")   # CJK runs, split into bigrams below
+_WS = re.compile(r"\s+")
+
+
+def _num(value, default=0.0):
+    try:
+        number = float(value)
+    except Exception:
+        return float(default)
+    if not math.isfinite(number):
+        return float(default)
+    return number
+
+
+def _clamp(value, low=0.0, high=1.0):
+    return max(low, min(high, _num(value, low)))
+
+
+def enabled(flags=None, env=None):
+    """spatial_recall: explicit flag > nested switches > env > default OFF."""
+    data = flags if isinstance(flags, dict) else {}
+    if isinstance(data.get(SWITCH_KEY), bool):
+        return data[SWITCH_KEY]
+    switches = data.get("switches") if isinstance(data.get("switches"), dict) else {}
+    if isinstance(switches.get(SWITCH_KEY), bool):
+        return switches[SWITCH_KEY]
+    environ = env if hasattr(env, "get") else None
+    if environ is not None and ENV_KEY in environ:
+        raw = str(environ.get(ENV_KEY)).strip().lower()
+        if raw in ("1", "true", "on", "yes"):
+            return True
+        if raw in ("0", "false", "off", "no"):
+            return False
+    return False
+
+
+def tokens(text):
+    """Deterministic bag: latin words + CJK bigrams + single characters.
+
+    Bigrams are what the governance concept extractor produces, so a query and
+    an entry's topics line up when no embedding is available.
+    """
+    body = _WS.sub(" ", str(text or "")).lower()
+    out = _TOKEN.findall(body)
+    for run in _CJK_RUN.findall(body):
+        if len(run) == 1:
+            out.append(run)
+            continue
+        out.extend(run[index:index + 2] for index in range(len(run) - 1))
+        out.extend(run)
+    seen = []
+    for item in out:
+        if item not in seen:
+            seen.append(item)
+    return seen
+
+
+def fingerprint(text):
+    body = _WS.sub(" ", str(text or "")).strip().lower()
+    return hashlib.sha1(body.encode("utf-8")).hexdigest()[:FINGERPRINT_CHARS]
+
+
+def half_life_minutes(entry):
+    """Per-entry half-life: the kind's base, scaled by importance."""
+    entry = entry if isinstance(entry, dict) else {}
+    kind = str(entry.get("kind") or entry.get("memory_kind") or "direct")
+    base = HALF_LIFE_BY_KIND.get(kind, BASE_HALF_LIFE_MINUTES)
+    importance = _clamp(entry.get("importance", DEFAULT_IMPORTANCE))
+    return round(base * (1.0 - IMPORTANCE_SPAN + 2.0 * IMPORTANCE_SPAN * importance),
+                 3)
+
+
+def _vector(entry):
+    raw = entry.get("vector") if isinstance(entry, dict) else None
+    if not isinstance(raw, (list, tuple)):
+        return []
+    out = []
+    for value in raw[:VECTOR_LIMIT]:
+        try:
+            number = float(value)
+        except Exception:
+            continue
+        if math.isfinite(number):
+            out.append(round(number, 6))
+    return out
+
+
+def _tags(values, limit):
+    if isinstance(values, str):
+        values = [values]
+    if not isinstance(values, (list, tuple)):
+        return []
+    out = []
+    for value in values:
+        text = str(value or "").strip()
+        if text and text not in out:
+            out.append(text[:32])
+    return out[:limit]   # tags first, then concepts: order is meaningful
+
+
+def _embed_names(entry, embed=None):
+    """Provider / model of the embedding, so mismatches are visible at a glance."""
+    entry = entry if isinstance(entry, dict) else {}
+    info = embed if isinstance(embed, dict) else {}
+    provider = str(info.get("provider")
+                   or entry.get("embedding_provider")
+                   or entry.get("vector_provider")
+                   or entry.get("embed_provider") or "")[:64]
+    model = str(info.get("model")
+                or entry.get("embedding_model")
+                or entry.get("vector_model")
+                or entry.get("embed_model") or "")[:64]
+    return provider, model
+
+
+def build(entry, relationship=None, now=None, embed=None):
+    """Five-axis coordinates for one entry; None when they cannot be built."""
+    try:
+        return _build(entry, relationship, now, embed)
+    except Exception:      # a broken entry never breaks the write
+        return None
+
+
+def _build(entry, relationship=None, now=None, embed=None):
+    if not isinstance(entry, dict):
+        return None      # nothing to put coordinates on
+    rel = relationship if isinstance(relationship, dict) else {}
+    embed_provider, embed_model = _embed_names(entry, embed)
+    stamp = _num(now, _num(entry.get("ts"), 0.0))
+    ts = round(_num(entry.get("ts"), stamp), 3)
+    vector = _vector(entry)
+    topics = _tags(list(entry.get("tags") or []) + list(entry.get("concepts") or []),
+                   TOPIC_LIMIT)
+    entities = _tags(entry.get("entities") or entry.get("entity"), ENTITY_LIMIT)
+    affect = entry.get("affect") if isinstance(entry.get("affect"), dict) else {}
+    trust = rel.get("trust", entry.get("trust", DEFAULT_TRUST))
+    closeness = rel.get("closeness", entry.get("closeness", DEFAULT_CLOSENESS))
+    return {
+        "schema": SCHEMA,
+        "semantic": {
+            "vector": vector,
+            "vector_dim": len(vector),
+            # true = tags only; never pretend a vector exists
+            "fallback": not bool(vector),
+            "provider": embed_provider,
+            "model": embed_model,
+            "topics": topics,
+            "entities": entities,
+            "fingerprint": fingerprint(entry.get("text")),
+        },
+        "time": {
+            "ts": ts,
+            "half_life_minutes": half_life_minutes(entry),
+            "age_minutes": round(max(0.0, stamp - ts) / 60.0, 3),
+            "last_hit_ts": round(_num(entry.get("last_hit_ts"), 0.0), 3),
+        },
+        "affect": {
+            "v": round(_clamp(affect.get("v", entry.get("v", 0.0)), -1.0, 1.0), 6),
+            "a": round(_clamp(affect.get("a", entry.get("a", 0.5))), 6),
+        },
+        "social": {
+            "scope": str(entry.get("scope") or entry.get("session_id") or "default")[:64],
+            "trust": round(_clamp(trust), 6),
+            "closeness": round(_clamp(closeness), 6),
+        },
+        "activation": {
+            "importance": round(_clamp(entry.get("importance", DEFAULT_IMPORTANCE)), 6),
+            "hits": int(_num(entry.get("hits"), 1)),
+            "retrieval_count": int(_num(entry.get("retrieval_count"), 0)),
+            "last_hit_ts": round(_num(entry.get("last_hit_ts"), 0.0), 3),
+        },
+    }
+
+
+# ------------------------------------------------------------------ distance
+def _cosine_distance(x, y):
+    dot = sum(a * b for a, b in zip(x, y))
+    norm_x = math.sqrt(sum(a * a for a in x))
+    norm_y = math.sqrt(sum(b * b for b in y))
+    if norm_x <= 0 or norm_y <= 0:
+        return 1.0
+    return _clamp(1.0 - dot / (norm_x * norm_y), 0.0, 2.0)
+
+
+def _semantic_distance(x, y):
+    x = x if isinstance(x, dict) else {}
+    y = y if isinstance(y, dict) else {}
+    vx = _vector({"vector": x.get("vector")})
+    vy = _vector({"vector": y.get("vector")})
+    if vx and vy and len(vx) == len(vy):
+        # 1 - cosine: 0 for the same direction, 2 for the opposite one
+        return round(_clamp(_cosine_distance(vx, vy), 0.0, 2.0), 6)
+    tx, ty = set(x.get("topics") or []), set(y.get("topics") or [])
+    ex, ey = set(x.get("entities") or []), set(y.get("entities") or [])
+    union = tx | ty | ex | ey
+    if not union:
+        return 1.0
+    shared = (tx & ty) | (ex & ey)
+    return round(1.0 - len(shared) / len(union), 6)
+
+
+def _time_distance(x, y):
+    x = x if isinstance(x, dict) else {}
+    y = y if isinstance(y, dict) else {}
+    gap = abs(_num(x.get("ts"), 0.0) - _num(y.get("ts"), 0.0))
+    scale = max(1.0, _num(x.get("half_life_minutes"), BASE_HALF_LIFE_MINUTES),
+                _num(y.get("half_life_minutes"), BASE_HALF_LIFE_MINUTES)) * 60.0
+    return round(_clamp(gap / scale), 6)
+
+
+def _affect_distance(x, y):
+    x = x if isinstance(x, dict) else {}
+    y = y if isinstance(y, dict) else {}
+    dv = _num(x.get("v"), 0.0) - _num(y.get("v"), 0.0)
+    da = _num(x.get("a"), 0.5) - _num(y.get("a"), 0.5)
+    return round(_clamp(math.sqrt((dv * dv + da * da) / 2.0)), 6)
+
+
+def _social_distance(x, y):
+    x = x if isinstance(x, dict) else {}
+    y = y if isinstance(y, dict) else {}
+    scope = 0.0 if str(x.get("scope") or "") == str(y.get("scope") or "") else 1.0
+    spread = (abs(_num(x.get("trust"), DEFAULT_TRUST)
+                  - _num(y.get("trust"), DEFAULT_TRUST))
+              + abs(_num(x.get("closeness"), DEFAULT_CLOSENESS)
+                    - _num(y.get("closeness"), DEFAULT_CLOSENESS))) / 2.0
+    return round(_clamp(0.5 * scope + 0.5 * spread), 6)
+
+
+def _activation_distance(x, y):
+    x = x if isinstance(x, dict) else {}
+    y = y if isinstance(y, dict) else {}
+    importance = abs(_num(x.get("importance"), DEFAULT_IMPORTANCE)
+                     - _num(y.get("importance"), DEFAULT_IMPORTANCE))
+    ceiling = math.log1p(HITS_CEILING)
+    hits = abs(math.log1p(max(0.0, _num(x.get("hits"), 0.0)))
+               - math.log1p(max(0.0, _num(y.get("hits"), 0.0)))) / ceiling
+    return round(_clamp(0.6 * importance + 0.4 * hits), 6)
+
+
+def distance(space_a, space_b):
+    """Per-axis distance; there is no total, on purpose."""
+    a = space_a if isinstance(space_a, dict) else {}
+    b = space_b if isinstance(space_b, dict) else {}
+    return {
+        "semantic": _semantic_distance(a.get("semantic"), b.get("semantic")),
+        "time": _time_distance(a.get("time"), b.get("time")),
+        "affect": _affect_distance(a.get("affect"), b.get("affect")),
+        "social": _social_distance(a.get("social"), b.get("social")),
+        "activation": _activation_distance(a.get("activation"),
+                                           b.get("activation")),
+    }
+
+
+def order_key(distances):
+    """Lexicographic order over the axes; nothing is summed."""
+    row = distances if isinstance(distances, dict) else {}
+    return tuple(_num(row.get(axis), 1.0) for axis in DISTANCE_ORDER)
+
+
+# --------------------------------------------------------------------- probe
+def query_space(query, vector=None, now=None, embed=None):
+    """Coordinates for a bare query string (same five axes, no id)."""
+    return build({"text": query, "vector": vector or [],
+                  "ts": _num(now, 0.0), "tags": tokens(query),
+                  "importance": DEFAULT_IMPORTANCE}, now=now, embed=embed)
+
+
+def probe(entries, entry_id=None, query=None, vector=None, limit=5, now=None):
+    """Debug read: one entry's five axes, or the nearest entries to a query."""
+    rows = [row for row in (entries or []) if isinstance(row, dict)]
+    limit = max(1, min(20, int(_num(limit, 5))))
+    if entry_id:
+        want = str(entry_id)
+        for row in rows:
+            if str(row.get("id") or "") == want:
+                stored = row.get("space")
+                space = stored if isinstance(stored, dict) else build(row, now=now)
+                return {"ok": space is not None, "id": want,
+                        "source": "entry" if isinstance(stored, dict) else "computed",
+                        "space": space,
+                        "reason": "" if space is not None else "build_failed"}
+        return {"ok": False, "reason": "not_found", "id": want}
+    if query:
+        target = query_space(query, vector=vector, now=now)
+        scored = []
+        for row in rows:
+            stored = row.get("space")
+            space = stored if isinstance(stored, dict) else build(row, now=now)
+            if not isinstance(space, dict):
+                continue
+            distances = distance(space, target)
+            scored.append({"id": str(row.get("id") or ""),
+                           "text": str(row.get("text") or "")[:80],
+                           "ts": round(_num(row.get("ts"), 0.0), 3),
+                           "distance": distances,
+                           "from": "entry" if isinstance(stored, dict) else "computed"})
+        scored.sort(key=lambda item: order_key(item["distance"]))
+        return {"ok": True, "query": str(query), "count": len(scored),
+                "limit": limit, "order": list(DISTANCE_ORDER),
+                "space": target, "results": scored[:limit]}
+    return {"ok": False, "reason": "id_or_query_required"}

package/python/biocore_memory/store/dedupe.py

@@ -18,6 +18,7 @@ import unicodedata
 from ..core.util import clamp01
 from ..index.entities import cues
 
+# [engineering] the four-level rules and these thresholds are hand-set.
 L1_MERGE = 0.90
 L1_FLAG = 0.75
 L3_WINDOW_SECONDS = 60.0

package/python/biocore_memory/store/tiering.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import time
 
-TIERING_ENABLED = False
+TIERING_ENABLED = True
 HOT_BUDGET = 80
 WARM_BUDGET = 200
 TIER_UNLIMITED = 10 ** 9
@@ -12,6 +12,7 @@ HOT_AGE_SECONDS = 24 * 3600
 WARM_AGE_SECONDS = 30 * 86400
 HOT_IMPORTANCE = 0.80
 HOT_HITS = 5
+HOT_EXIT_HITS = 3  # hysteresis: a hot entry leaves only below this
 
 
 def _num(entry, keys, default=0.0):
@@ -33,8 +34,12 @@ def _age(entry, now):
     return max(0.0, float(now) - last)
 
 
-def tier_of(entry, now=None):
-    """Return 'hot' | 'warm' | 'cold'; disabled tiering is neutral ('warm')."""
+def tier_of(entry, now=None, previous=None):
+    """Return 'hot' | 'warm' | 'cold'; disabled tiering is neutral ('warm').
+
+    Hysteresis (task-36): a hot entry stays hot until hits drop below
+    HOT_EXIT_HITS, so a value hovering at the boundary cannot flicker.
+    """
     if not TIERING_ENABLED or not isinstance(entry, dict):
         return "warm"
     try:
@@ -42,6 +47,12 @@ def tier_of(entry, now=None):
         age = _age(entry, stamp)
         importance = _num(entry, ("importance",), 0.5)
         hits = _num(entry, ("hits", "visits", "visit_count"), 0.0)
+        if previous == "hot":
+            if hits >= HOT_EXIT_HITS:
+                return "hot"
+            if age <= WARM_AGE_SECONDS or hits >= 2:
+                return "warm"
+            return "cold"
         if age <= HOT_AGE_SECONDS or importance >= HOT_IMPORTANCE or hits >= HOT_HITS:
             return "hot"
         if age <= WARM_AGE_SECONDS or hits >= 2:

package/python/biocore_model/affective_labor.py

@@ -26,7 +26,7 @@ DIM_WEIGHTS = {
     "trust": 0.10,
     "stress": 0.10,
 }
-MASK_COST = 0.22
+MASK_COST = 0.22  # [engineering] energy cost of surface acting, hand-tuned
 LOAD_DECAY_PER_HOUR = 0.03
 BREAKDOWN_THRESHOLD = 0.85
 
@@ -121,6 +121,12 @@ def update(labor_state, expressed, felt, honesty=0.0, now=0.0,
     load = _clamp01(load + cost)
     data["load"] = round(load, 4)
     data["last_cost"] = cost
+    # Three components stay separate: a single "cost" hid which one moved.
+    data["components"] = {
+        "emotional_exhaustion": round(load, 4),
+        "depersonalization": round(mask, 4),
+        "personal_accomplishment": round(max(0.0, 1.0 - mask), 4),
+    }
     data["last_masking"] = mask
     data["turns"] = int(data.get("turns", 0) or 0) + 1
     if load >= BREAKDOWN_THRESHOLD and before < BREAKDOWN_THRESHOLD:
@@ -157,6 +163,13 @@ def view(labor_state):
         "collapsed": collapsed(data),
         "last_cost": round(_clamp01(data.get("last_cost", 0.0)), 4),
         "last_masking": round(_clamp01(data.get("last_masking", 0.0)), 4),
+        "components": {
+            "emotional_exhaustion": round(_clamp01(data.get("load", 0.0)), 4),
+            "depersonalization": round(
+                _clamp01(data.get("last_masking", 0.0)), 4),
+            "personal_accomplishment": round(
+                max(0.0, 1.0 - _clamp01(data.get("last_masking", 0.0))), 4),
+        },
         "turns": int(data.get("turns", 0) or 0),
         "breakdowns": int(data.get("breakdowns", 0) or 0),
     }