apsimo 1.3.0__py3-none-any.whl

apsimo/tom/asymmetry.py

@@ -0,0 +1,131 @@
+"""Knowledge-asymmetry engine (tom2, H3.2) — daily, default OFF.
+
+Compares the per-contact epistemic rows in SharedFactsStore and derives
+second-order inferences:
+
+  * ``knows``      — a contact knows the facts recorded for them;
+  * ``unaware_of`` — a contact has no equivalent of a (confident) fact
+                     another contact holds.
+
+Fact TEXT is compared in memory only; what persists (live mode) are
+Tom2Store rows holding fact IDS — the refs-not-content invariant is the
+store's hard write-time pin, this engine simply never has a reason to
+violate it.
+
+Modes (COLONY_TOM2): off (default, engine is inert) | shadow (counts only,
+writes nothing) | live (writes owner-only inference rows).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from typing import Any, Dict, List
+
+logger = logging.getLogger(__name__)
+
+# A cross-contact "unaware_of" is an inference, not an observation: born
+# modest, and only derived from reasonably confident source facts.
+_UNAWARE_CONFIDENCE = 0.4
+_MIN_SOURCE_CONFIDENCE = 0.6
+
+
+def tom2_mode() -> str:
+    from apsimo.util.autonomy_preset import resolve
+    return resolve("COLONY_TOM2", ("off", "shadow", "live"), "off")
+
+
+def tom2_context_enabled() -> bool:
+    """COLONY_TOM2_CONTEXT (default 0, H3.3): may tom2 inferences be
+    injected into the OWNER'S assembled context? Injection is additionally
+    keyed to the owner's contact identity at assembly time — this flag can
+    never widen the audience, only turn the owner section on."""
+    return os.environ.get("COLONY_TOM2_CONTEXT", "0").strip().lower() in (
+        "1", "true", "yes", "on")
+
+
+def _norm(text: Any) -> str:
+    return re.sub(r"\s+", " ", str(text or "").strip().lower())
+
+
+class AsymmetryEngine:
+    def __init__(self, facts_store: Any, tom2_store: Any,
+                 max_facts: int = 500,
+                 max_rows_per_contact: int = 50) -> None:
+        self._facts = facts_store
+        self._tom2 = tom2_store
+        self._max_facts = max_facts
+        self._max_rows = max_rows_per_contact
+        self.last_report: Dict[str, Any] = {}
+
+    def run(self) -> Dict[str, Any]:
+        mode = tom2_mode()
+        report: Dict[str, Any] = {"mode": mode, "contacts": 0, "knows": 0,
+                                  "unaware_of": 0, "written": 0}
+        self.last_report = report
+        if mode == "off" or self._facts is None or self._tom2 is None:
+            return report
+
+        try:
+            facts: List[Dict[str, Any]] = self._facts.list_facts(
+                limit=self._max_facts).get("facts", [])
+        except Exception:
+            logger.warning("tom2 asymmetry: facts unavailable", exc_info=True)
+            return report
+
+        by_contact: Dict[str, List[Dict[str, Any]]] = {}
+        for f in facts:
+            cid = str(f.get("contact_id") or "").strip()
+            if cid and f.get("id"):
+                by_contact.setdefault(cid, []).append(f)
+        contacts = sorted(by_contact)
+        report["contacts"] = len(contacts)
+
+        for cid in contacts:
+            own = by_contact[cid]
+            own_texts = {_norm(f.get("fact")) for f in own}
+
+            # First-order grounding: a contact knows their own rows.
+            for f in own:
+                report["knows"] += 1
+                if mode == "live":
+                    self._write(cid, "knows", f["id"],
+                                float(f.get("confidence") or 0.5), report)
+
+            # Cross-contact asymmetry: confident facts held elsewhere with
+            # no textual equivalent in this contact's rows. The text match
+            # happens HERE, in memory; only ids are ever written.
+            written_rows = 0
+            for other in contacts:
+                if other == cid:
+                    continue
+                for f in by_contact[other]:
+                    if float(f.get("confidence") or 0.0) < _MIN_SOURCE_CONFIDENCE:
+                        continue
+                    if _norm(f.get("fact")) in own_texts:
+                        continue
+                    report["unaware_of"] += 1
+                    if mode == "live" and written_rows < self._max_rows:
+                        if self._write(cid, "unaware_of", f["id"],
+                                       _UNAWARE_CONFIDENCE, report):
+                            written_rows += 1
+
+        logger.info(
+            "tom2 asymmetry[%s]: contacts=%d knows=%d unaware_of=%d written=%d",
+            mode, report["contacts"], report["knows"], report["unaware_of"],
+            report["written"])
+        return report
+
+    def _write(self, contact_id: str, kind: str, fact_ref: str,
+               confidence: float, report: Dict[str, Any]) -> bool:
+        try:
+            self._tom2.record_inference(
+                contact_id=contact_id, kind=kind, fact_ref=str(fact_ref),
+                confidence=confidence)
+            report["written"] += 1
+            return True
+        except Exception:
+            # A refused write (privacy pin) must never break the sweep.
+            logger.debug("tom2 inference write refused", exc_info=True)
+            return False

apsimo/tom/eligibility.py

@@ -0,0 +1,248 @@
+"""Level-2 eligibility pipeline (L2.1) — ordered, first-fail-wins.
+
+Decides whether ONE tom2 inference may be considered for level-2 rendering
+to ONE reader in ONE conversation. Every check must pass, in order; the
+first failure names itself (owner observability) and ends the evaluation.
+Any internal error is a failure — never an exemption.
+
+Order (each check exists for a specific threat):
+
+    1. subject-scope       — the subject is a real, resolvable contact and
+                             not the reader themself.
+    2. subject-owner       — the subject is never the owner (T9: "the owner
+                             hasn't heard X" must not be narrated to anyone).
+    3. subject-present     — the subject was NOT sighted in this conversation
+                             window (T5: never model someone into the room
+                             they are standing in).
+    4. ref-visibility      — the H3.5 double gate, delegated VERBATIM to
+                             tom.tom2.render_inference_for_contact: every ref
+                             must resolve to a fact row owned by the reader.
+                             This is the structural guarantee that level 2
+                             can never introduce new fact content.
+    5. mutual-knowledge    — M1: reader and subject demonstrably know of each
+                             other (a shared conversation sighting within
+                             COLONY_TOM2_MUTUAL_WINDOW_DAYS, default 30).
+    6. tier-floors         — M2: reader tier >= trusted, subject tier >=
+                             regular.
+    7. approval            — M3: the owner has approved this (reader,
+                             subject) pair (injected hook; required unless
+                             COLONY_TOM2_L2_APPROVAL=off).
+    8. budget              — M7: the exposure ledger has budget for this
+                             rendering (injected hook; no hook = no budget).
+
+This module is dark: nothing live calls it until the wiring tranche.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Union
+
+from apsimo.gate.env_risk import _tier_rank, env_risk_window_hours
+from apsimo.identity.participants import SYSTEM_CONTACT_ID
+from apsimo.tom.tom2 import render_inference_for_contact
+
+logger = logging.getLogger(__name__)
+
+CHECKS = ("subject-scope", "subject-owner", "subject-present",
+          "ref-visibility", "mutual-knowledge", "tier-floors",
+          "approval", "budget")
+
+#: Tier floors (M2): who may RECEIVE a level-2 line, who may be its SUBJECT.
+READER_FLOOR = "trusted"
+SUBJECT_FLOOR = "regular"
+
+HookResult = Union[bool, Awaitable[bool]]
+
+
+def l2_approval_mode() -> str:
+    """COLONY_TOM2_L2_APPROVAL: 'required' (default) or 'off'. Any other
+    value reads as 'required' (fail closed)."""
+    raw = os.environ.get("COLONY_TOM2_L2_APPROVAL", "required").strip().lower()
+    return "off" if raw == "off" else "required"
+
+
+def mutual_window_days() -> float:
+    """COLONY_TOM2_MUTUAL_WINDOW_DAYS (default 30): how recent the reader/
+    subject co-sighting must be to count as mutual knowledge."""
+    try:
+        v = float(os.environ.get("COLONY_TOM2_MUTUAL_WINDOW_DAYS", "30"))
+        return v if v > 0 else 30.0
+    except (TypeError, ValueError):
+        return 30.0
+
+
+@dataclass
+class EligibilityDecision:
+    eligible: bool
+    failed_check: Optional[str] = None
+    detail: str = ""
+    checks_passed: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"eligible": self.eligible, "failed_check": self.failed_check,
+                "detail": self.detail,
+                "checks_passed": list(self.checks_passed)}
+
+
+def _fail(check: str, detail: str,
+          passed: List[str]) -> EligibilityDecision:
+    return EligibilityDecision(eligible=False, failed_check=check,
+                               detail=detail, checks_passed=list(passed))
+
+
+async def _hook_ok(hook: Any, *args: Any) -> bool:
+    """Run an injected hook; anything but a clean truthy answer is False."""
+    if hook is None:
+        return False
+    try:
+        r = hook(*args)
+        if hasattr(r, "__await__"):
+            r = await r
+        return bool(r)
+    except Exception:
+        logger.debug("eligibility hook failed (=> ineligible)", exc_info=True)
+        return False
+
+
+async def evaluate_inference(
+    inference: Dict[str, Any],
+    *,
+    reader_contact_id: str,
+    conversation_key: str,
+    facts_store: Any,
+    contacts_store: Any,
+    presence_store: Any,
+    owner_id: Optional[str] = None,
+    approval_check: Optional[Callable[[str, str], HookResult]] = None,
+    budget_check: Optional[Callable[[str, str, str], HookResult]] = None,
+) -> EligibilityDecision:
+    """Run the full ordered pipeline for one inference. Never raises."""
+    try:
+        return await _evaluate(inference,
+                               reader_contact_id=reader_contact_id,
+                               conversation_key=conversation_key,
+                               facts_store=facts_store,
+                               contacts_store=contacts_store,
+                               presence_store=presence_store,
+                               owner_id=owner_id,
+                               approval_check=approval_check,
+                               budget_check=budget_check)
+    except Exception as exc:
+        logger.debug("eligibility evaluation failed (=> ineligible): %s",
+                     exc, exc_info=True)
+        return _fail("error", f"{type(exc).__name__}", [])
+
+
+async def _evaluate(inference, *, reader_contact_id, conversation_key,
+                    facts_store, contacts_store, presence_store, owner_id,
+                    approval_check, budget_check) -> EligibilityDecision:
+    passed: List[str] = []
+    reader = str(reader_contact_id or "").strip()
+    subject = str((inference or {}).get("contact_id") or "").strip()
+
+    # 1. subject-scope
+    if not isinstance(inference, dict) or not subject:
+        return _fail("subject-scope", "no subject", passed)
+    if not reader or reader == SYSTEM_CONTACT_ID:
+        return _fail("subject-scope", "no reader", passed)
+    if subject == reader or subject == SYSTEM_CONTACT_ID:
+        return _fail("subject-scope", "subject is reader/system", passed)
+    if contacts_store is None:
+        return _fail("subject-scope", "contacts store missing", passed)
+    subject_contact = await contacts_store.get(subject)
+    if subject_contact is None:
+        return _fail("subject-scope", "subject unresolvable", passed)
+    passed.append("subject-scope")
+
+    # 2. subject-owner (T9). Owner identity unknown fails closed: we cannot
+    # PROVE the subject is not the owner.
+    if owner_id is None:
+        from apsimo.identity.resolver import get_owner_contact_id
+        owner_id = get_owner_contact_id()
+    owner = str(owner_id or "").strip()
+    if not owner:
+        return _fail("subject-owner", "owner identity unset", passed)
+    if subject == owner:
+        return _fail("subject-owner", "subject is the owner", passed)
+    passed.append("subject-owner")
+
+    # 3. subject-present (T5). A broken/missing presence store cannot prove
+    # absence — fail closed.
+    if presence_store is None:
+        return _fail("subject-present", "presence store missing", passed)
+    try:
+        present = presence_store.is_present(
+            conversation_key, subject, window_hours=env_risk_window_hours())
+    except Exception:
+        return _fail("subject-present", "presence read failed", passed)
+    if present:
+        return _fail("subject-present", "subject sighted in conversation",
+                     passed)
+    passed.append("subject-present")
+
+    # 4. ref-visibility — the H3.5 gate, verbatim. None = ineligible,
+    # whether from partial visibility, a missing fact, or the master
+    # COLONY_TOM2_CROSS_CONTEXT flag being off.
+    if render_inference_for_contact(inference, facts_store, reader) is None:
+        return _fail("ref-visibility", "H3.5 gate refused", passed)
+    passed.append("ref-visibility")
+
+    # 5. mutual-knowledge (M1)
+    try:
+        mutual = presence_store.cooccurred(reader, subject,
+                                           within_days=mutual_window_days())
+    except Exception:
+        return _fail("mutual-knowledge", "cooccurrence read failed", passed)
+    if not mutual:
+        return _fail("mutual-knowledge",
+                     "no recent shared conversation", passed)
+    passed.append("mutual-knowledge")
+
+    # 6. tier-floors (M2)
+    reader_contact = await contacts_store.get(reader)
+    if reader_contact is None:
+        return _fail("tier-floors", "reader unresolvable", passed)
+    if _tier_rank(getattr(reader_contact, "trust_tier", "")) <\
+            _tier_rank(READER_FLOOR):
+        return _fail("tier-floors", "reader below trusted", passed)
+    if _tier_rank(getattr(subject_contact, "trust_tier", "")) <\
+            _tier_rank(SUBJECT_FLOOR):
+        return _fail("tier-floors", "subject below regular", passed)
+    passed.append("tier-floors")
+
+    # 7. approval (M3)
+    if l2_approval_mode() == "off":
+        passed.append("approval")
+    elif await _hook_ok(approval_check, reader, subject):
+        passed.append("approval")
+    else:
+        return _fail("approval", "pair not approved by owner", passed)
+
+    # 8. budget (M7): no ledger, no budget.
+    fact_ref = str((inference or {}).get("fact_ref") or "")
+    if not await _hook_ok(budget_check, reader, subject, fact_ref):
+        return _fail("budget", "no exposure budget", passed)
+    passed.append("budget")
+
+    return EligibilityDecision(eligible=True, checks_passed=passed)
+
+
+async def eligible_inferences(rows: List[Dict[str, Any]], *,
+                              limit: int = 5, **kwargs: Any
+                              ) -> List[Dict[str, Any]]:
+    """Filter inference rows through the pipeline (order preserved), up to
+    ``limit`` eligible results. Errors inside any evaluation drop that row."""
+    out: List[Dict[str, Any]] = []
+    limit = max(0, int(limit))
+    if limit == 0:
+        return out
+    for row in rows or []:
+        decision = await evaluate_inference(row, **kwargs)
+        if decision.eligible:
+            out.append(row)
+        if len(out) >= limit:
+            break
+    return out

apsimo/tom/engagement.py

@@ -0,0 +1,214 @@
+"""Read current attributed engagement observations; retain numeric history only.
+
+Canonical source claims own preferences; AppraisalStore projects them. Legacy
+aggregates remain inspectable but no longer produce psychological certainty.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Numeric dimensions. OCEAN are signed (-1 low .. +1 high); style are 0..1.
+OCEAN = ("openness", "conscientiousness", "extraversion", "agreeableness", "neuroticism")
+STYLE = ("formality", "directness", "warmth", "verbosity", "emoji_ok", "humor")
+_ALL_DIMS = OCEAN + STYLE
+_QUAL_KEYS = ("motivators", "topics", "avoid")
+_QUAL_CAP = 8
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+from .source_lineage import SourceLinkedStore
+
+
+class EngagementStore(SourceLinkedStore):
+    """SQLite-backed evolving engagement profile per contact."""
+
+    def __init__(self, db_path: str, *, source_ledger=None) -> None:
+        self._db_path = str(db_path)
+        self._source_ledger = source_ledger
+        self._conn = sqlite3.connect(self._db_path)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS engagement_profiles (
+                contact_id TEXT PRIMARY KEY,
+                dims_json TEXT NOT NULL DEFAULT '{}',
+                qual_json TEXT NOT NULL DEFAULT '{}',
+                observation_count INTEGER NOT NULL DEFAULT 0,
+                updated_at TEXT NOT NULL
+            );
+            """
+        )
+        # Capture old aggregate profiles once, without inventing source links.
+        # New observations are separate so deletion can replay their EMA exactly.
+        with self._conn:
+            self._conn.execute('BEGIN IMMEDIATE')
+            first = not self._conn.execute("SELECT 1 FROM sqlite_master WHERE name='engagement_baselines'").fetchone()
+            self._conn.execute("""CREATE TABLE IF NOT EXISTS engagement_baselines (
+                contact_id TEXT PRIMARY KEY, dims_json TEXT NOT NULL, qual_json TEXT NOT NULL,
+                observation_count INTEGER NOT NULL, updated_at TEXT NOT NULL,
+                evidence_basis TEXT NOT NULL DEFAULT 'legacy_unlinked')""")
+            self._conn.execute("""CREATE TABLE IF NOT EXISTS engagement_observations (
+                id INTEGER PRIMARY KEY AUTOINCREMENT, contact_id TEXT NOT NULL,
+                observation_json TEXT NOT NULL, source_lineage_json TEXT, created_at TEXT NOT NULL)""")
+            self._conn.execute('CREATE INDEX IF NOT EXISTS idx_engagement_observation_contact ON engagement_observations(contact_id)')
+            if first:
+                self._conn.execute("""INSERT INTO engagement_baselines
+                    (contact_id,dims_json,qual_json,observation_count,updated_at)
+                    SELECT contact_id,dims_json,qual_json,observation_count,updated_at FROM engagement_profiles""")
+
+    def purge_erased_sources(self, turn_ids=None, *, contact_id=None) -> int:
+        sql = 'SELECT id,contact_id,source_lineage_json FROM engagement_observations WHERE source_lineage_json IS NOT NULL'
+        rows = self._conn.execute(sql + (' AND contact_id=?' if contact_id else ''),
+                                  (contact_id,) if contact_id else ()).fetchall()
+        invalid = self._invalid_sources(rows, turn_ids)
+        with self._conn:
+            self._conn.executemany('DELETE FROM engagement_observations WHERE id=?', [(row['id'],) for row in invalid])
+            for person in {row['contact_id'] for row in invalid}:
+                self._recompute_profile(person)
+        return len(invalid)
+
+    # -- read ---------------------------------------------------------------
+    def _row(self, contact_id: str) -> Optional[sqlite3.Row]:
+        return self._conn.execute(
+            "SELECT * FROM engagement_profiles WHERE contact_id=?", (contact_id,)
+        ).fetchone()
+
+    def get_profile(self, contact_id: str) -> Dict[str, Any]:
+        self.purge_erased_sources(contact_id=contact_id)
+        row = self._row(contact_id)
+        baseline = self._conn.execute('SELECT observation_count FROM engagement_baselines WHERE contact_id=?', (contact_id,)).fetchone()
+        dims_raw = json.loads(row["dims_json"] or "{}") if row else {}
+        observations = []
+        if self._source_ledger is not None:
+            from apsimo.identity import get_owner_contact_id
+            from apsimo.self_model.appraisals import AppraisalStore
+            observations = AppraisalStore(self._source_ledger, owner_id=get_owner_contact_id()).view(
+                contact_id, viewer_contact_id=contact_id)['records']
+        return {
+            "contact_id": contact_id, "dims": {}, "qual": {},
+            "observations": observations, "observation_count": len(observations),
+            "legacy_profile": {"dims": dims_raw, "qual": json.loads(row["qual_json"] or "{}") if row else {},
+                "observation_count": row["observation_count"] if row else 0, "governing": False},
+            "updated_at": row["updated_at"] if row else None,
+            "legacy_unlinked_observations": baseline[0] if baseline else 0,
+        }
+
+    # -- write --------------------------------------------------------------
+    def update_from_observation(
+        self,
+        contact_id: str,
+        ocean: Optional[Dict[str, Any]] = None,
+        style: Optional[Dict[str, Any]] = None,
+        motivators: Optional[List[str]] = None,
+        topics: Optional[List[str]] = None,
+        avoid: Optional[List[str]] = None,
+        source_lineage: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Fold one observation into the contact's evolving profile (EMA per dim)."""
+        if not contact_id:
+            return
+        if source_lineage is not None and not self._source_visible(contact_id, source_lineage):
+            from apsimo.turns.idempotency import SourceErased
+            raise SourceErased('source_erased')
+        self.purge_erased_sources(contact_id=contact_id)
+        observation = dict(ocean=ocean, style=style, motivators=motivators, topics=topics, avoid=avoid)
+        with self._conn:
+            self._conn.execute("""INSERT INTO engagement_observations
+                (contact_id,observation_json,source_lineage_json,created_at) VALUES (?,?,?,?)""",
+                (contact_id, json.dumps(observation), json.dumps(source_lineage) if source_lineage is not None else None, _now()))
+            row = self._row(contact_id)
+            dims = json.loads(row['dims_json']) if row else {}
+            qual = json.loads(row['qual_json']) if row else {}
+            self._fold(dims, qual, **observation)
+            self._write_profile(contact_id, dims, qual, (row['observation_count'] if row else 0) + 1, _now())
+        # Erasure can commit while the projection database is being written.
+        if source_lineage is not None and not self._source_visible(contact_id, source_lineage):
+            self.purge_erased_sources(contact_id=contact_id)
+            from apsimo.turns.idempotency import SourceErased
+            raise SourceErased('source_erased')
+
+    @staticmethod
+    def _fold(dims, qual, *, ocean=None, style=None, motivators=None, topics=None, avoid=None):
+        obs = dict(ocean or {})
+        obs.update(style or {})
+        for dim, val in obs.items():
+            if dim not in _ALL_DIMS or val is None:
+                continue
+            try:
+                val = float(val)
+            except (TypeError, ValueError):
+                continue
+            lo = -1.0 if dim in OCEAN else 0.0
+            val = max(lo, min(1.0, val))
+            cur = dims.get(dim)
+            if cur is None:
+                dims[dim] = {"v": round(val, 4), "n": 1}
+            else:
+                n = cur["n"] + 1
+                alpha = max(0.15, 1.0 / n)  # responsive early, stabilises later
+                v = cur["v"] + alpha * (val - cur["v"])
+                dims[dim] = {"v": round(v, 4), "n": n}
+
+        for key, items in (("motivators", motivators), ("topics", topics), ("avoid", avoid)):
+            if not items:
+                continue
+            existing = list(qual.get(key, []))
+            seen = {s.lower() for s in existing}
+            for it in items:
+                it = (it or "").strip()
+                if it and it.lower() not in seen:
+                    existing.append(it)
+                    seen.add(it.lower())
+            qual[key] = existing[-_QUAL_CAP:]  # keep most recent
+
+    def _recompute_profile(self, contact_id):
+        baseline = self._conn.execute('SELECT * FROM engagement_baselines WHERE contact_id=?', (contact_id,)).fetchone()
+        rows = self._conn.execute('SELECT * FROM engagement_observations WHERE contact_id=? ORDER BY id', (contact_id,)).fetchall()
+        if not baseline and not rows:
+            self._conn.execute('DELETE FROM engagement_profiles WHERE contact_id=?', (contact_id,))
+            return
+        dims = json.loads(baseline['dims_json']) if baseline else {}
+        qual = json.loads(baseline['qual_json']) if baseline else {}
+        count = baseline['observation_count'] if baseline else 0
+        updated = baseline['updated_at'] if baseline else None
+        for row in rows:
+            self._fold(dims, qual, **json.loads(row['observation_json']))
+            count += 1
+            updated = row['created_at']
+        self._write_profile(contact_id, dims, qual, count, updated)
+
+    def _write_profile(self, contact_id, dims, qual, count, updated):
+        self._conn.execute(
+            """INSERT INTO engagement_profiles (contact_id, dims_json, qual_json, observation_count, updated_at)
+               VALUES (?,?,?,?,?)
+               ON CONFLICT(contact_id) DO UPDATE SET
+                 dims_json=excluded.dims_json, qual_json=excluded.qual_json,
+                 observation_count=excluded.observation_count, updated_at=excluded.updated_at""",
+            (contact_id, json.dumps(dims), json.dumps(qual), count, updated),
+        )
+
+    def purge(self, contact_id: str) -> None:
+        with self._conn:
+            self._conn.execute("DELETE FROM engagement_profiles WHERE contact_id=?", (contact_id,))
+            self._conn.execute("DELETE FROM engagement_observations WHERE contact_id=?", (contact_id,))
+            self._conn.execute("DELETE FROM engagement_baselines WHERE contact_id=?", (contact_id,))
+
+
+def build_guidance(profile: Dict[str, Any]) -> str:
+    """Only current attributed preferences; numeric legacy profiles never govern."""
+    lines = []
+    for item in profile.get('observations', [])[:4]:
+        if item.get('kind') != 'preference' or item.get('status') != 'current' or not item.get('sources'):
+            continue
+        lines.append('Stated preference (attributed, correctable): ' + str(item.get('text', '')))
+    return '\n'.join(lines)