"""Deterministic long-term companion relationship settlement. This module owns the bounded relationship score. It deliberately does not grant identity, owner, memory, proactive, tool, or P4 authority. """ from __future__ import annotations from copy import deepcopy from datetime import datetime, timezone from hashlib import sha256 from math import isfinite from typing import Any try: from .relationship_policy import ( RELATIONSHIP_SCORE_MAX, RELATIONSHIP_SCORE_MIN, normalize_relationship_stage_policy, relationship_stage_for_score, ) except ImportError: # pragma: no cover - direct-module test compatibility from relationship_policy import ( RELATIONSHIP_SCORE_MAX, RELATIONSHIP_SCORE_MIN, normalize_relationship_stage_policy, relationship_stage_for_score, ) OWNER_EXCLUSIVE_MODE = "owner_exclusive" NORMAL_RELATIONSHIP_MODE = "normal" DEFAULT_POSITIVE_DAILY_CAP = 12 DEFAULT_EVENT_WINDOW_SECONDS = 30 * 60 DEFAULT_DECAY_GRACE_DAYS = 3 RELATIONSHIP_POSITIVE_STAGE_CAP_KEYS = ( "familiar", "close", "intimate", "deeply_bonded", ) DEFAULT_RELATIONSHIP_POSITIVE_STAGE_CAP_KEY = "deeply_bonded" _POSITIVE_STAGE_SCORE_MAX = { "familiar": 599, "close": 899, "intimate": 1199, "deeply_bonded": RELATIONSHIP_SCORE_MAX, } def normalize_relationship_mode(value: Any, role: Any) -> str: mode = str(value or "").strip().lower() normalized_role = str(role or "").strip().lower() if mode == OWNER_EXCLUSIVE_MODE and normalized_role == "owner": return OWNER_EXCLUSIVE_MODE return NORMAL_RELATIONSHIP_MODE def is_owner_exclusive(user: Any) -> bool: if not isinstance(user, dict): return False return normalize_relationship_mode(user.get("relationship_mode"), user.get("relationship_role")) == OWNER_EXCLUSIVE_MODE def normalize_relationship_positive_stage_cap_key(value: Any) -> str: """Return the configured ordinary-user positive relationship ceiling.""" key = str(value or "").strip().lower() return key if key in RELATIONSHIP_POSITIVE_STAGE_CAP_KEYS else DEFAULT_RELATIONSHIP_POSITIVE_STAGE_CAP_KEY def relationship_positive_score_cap(value: Any) -> int: return _POSITIVE_STAGE_SCORE_MAX[normalize_relationship_positive_stage_cap_key(value)] def _effective_positive_stage_cap_key(user: dict[str, Any], configured: Any = None) -> str: return normalize_relationship_positive_stage_cap_key( configured if configured is not None else user.get("relationship_positive_stage_cap_key") ) def apply_relationship_event( user: Any, delta: Any, *, reason_code: Any, now: Any = None, event_id: Any = None, positive_daily_cap: int = DEFAULT_POSITIVE_DAILY_CAP, event_window_seconds: int = DEFAULT_EVENT_WINDOW_SECONDS, positive_event_cap: int = 4, negative_event_cap: int = 12, positive_stage_cap_key: Any = None, ) -> dict[str, Any]: """Settle one auditable relationship event into the bounded score.""" if not isinstance(user, dict): return _result(False, "invalid_user") numeric_delta = _integer(delta) if numeric_delta is None or numeric_delta == 0: return _result(False, "invalid_delta") reason = _reason(reason_code) if not reason: return _result(False, "missing_reason") ts = _timestamp(now) role = str(user.get("relationship_role") or "").strip().lower() mode = normalize_relationship_mode(user.get("relationship_mode"), role) user["relationship_mode"] = mode if mode == OWNER_EXCLUSIVE_MODE: return _result(False, "owner_exclusive_frozen", score=_score(user.get("relationship_score"))) ledger = user.setdefault("relationship_ledger", []) if not isinstance(ledger, list): ledger = [] user["relationship_ledger"] = ledger dedupe_key = _event_key(reason, ts, event_id, max(60, int(event_window_seconds or DEFAULT_EVENT_WINDOW_SECONDS))) if any(isinstance(item, dict) and item.get("event_key") == dedupe_key for item in ledger[-200:]): return _result(False, "duplicate_event", score=_score(user.get("relationship_score"))) positive_cap = max(1, min(30, int(positive_event_cap or 4))) negative_cap = max(1, min(60, int(negative_event_cap or 12))) requested = max(-negative_cap, min(positive_cap, numeric_delta)) before = _score(user.get("relationship_score")) if requested > 0 and before >= 900: requested = max(1, (requested + 1) // 2) elif requested > 0 and before >= 600: requested = max(1, (requested * 3 + 3) // 4) applied = requested day_key = datetime.fromtimestamp(ts, tz=timezone.utc).date().isoformat() totals = user.setdefault("relationship_daily_totals", {}) if not isinstance(totals, dict) or totals.get("day") != day_key: totals = {"day": day_key, "positive": 0, "negative": 0} user["relationship_daily_totals"] = totals if applied > 0: raw_daily_cap = DEFAULT_POSITIVE_DAILY_CAP if positive_daily_cap is None else positive_daily_cap cap = max(0, min(120, int(raw_daily_cap))) remaining = max(0, cap - _bounded_int(totals.get("positive"), 0, 0, cap)) applied = min(applied, remaining) if applied <= 0: return _result(False, "positive_daily_cap", score=_score(user.get("relationship_score"))) positive_score_cap = relationship_positive_score_cap(_effective_positive_stage_cap_key(user, positive_stage_cap_key)) after = max(RELATIONSHIP_SCORE_MIN, min(RELATIONSHIP_SCORE_MAX, before + applied)) if applied > 0: after = min(after, positive_score_cap) applied = after - before if applied == 0: code = "positive_stage_cap" if requested > 0 and before >= positive_score_cap else "score_bound" return _result(False, code, score=before) user["relationship_score"] = after if applied > 0: totals["positive"] = _bounded_int(totals.get("positive"), 0, 0, 120) + applied user["relationship_last_effective_at"] = ts else: totals["negative"] = _bounded_int(totals.get("negative"), 0, -120, 0) + applied entry = { "event_key": dedupe_key, "reason_code": reason, "delta": applied, "score_before": before, "score_after": after, "created_at": ts, } ledger.append(entry) if len(ledger) > 200: del ledger[:-200] return _result(True, "applied", score=after, delta=applied, entry=deepcopy(entry)) def clamp_relationship_positive_stage_cap( user: Any, *, cap_key: Any = None, now: Any = None, reason_code: Any = "relationship_positive_stage_cap_runtime_clamp", ) -> dict[str, Any]: """Clamp a normal positive score and append one auditable runtime entry.""" if not isinstance(user, dict): return _result(False, "invalid_user") key = _effective_positive_stage_cap_key(user, cap_key) user["relationship_positive_stage_cap_key"] = key if is_owner_exclusive(user): return _result(False, "owner_exclusive_exempt", score=_score(user.get("relationship_score"))) before = _score(user.get("relationship_score")) if before <= 0: return _result(False, "non_positive_score_exempt", score=before) maximum = relationship_positive_score_cap(key) if before <= maximum: return _result(False, "within_positive_stage_cap", score=before) after = maximum user["relationship_score"] = after return _append_cap_audit_entry( user, before=before, after=after, now=now, reason_code=reason_code, metadata={"cap_key": key, "cap_max": maximum}, ) def migrate_relationship_positive_stage_cap( user: Any, *, old_cap_key: Any, new_cap_key: Any, now: Any = None, ) -> dict[str, Any]: """Lower an existing ordinary score proportionally exactly once per transition.""" if not isinstance(user, dict): return _result(False, "invalid_user") old_key = normalize_relationship_positive_stage_cap_key(old_cap_key) new_key = normalize_relationship_positive_stage_cap_key(new_cap_key) user["relationship_positive_stage_cap_key"] = new_key old_max = relationship_positive_score_cap(old_key) new_max = relationship_positive_score_cap(new_key) # Configuration elevation begins a new future lowering generation even for # an owner or currently non-positive record. Otherwise its old marker # would incorrectly suppress a later real lowering after that exemption # no longer applies. if new_max > old_max: user.pop("relationship_positive_stage_cap_migration", None) return _result(False, "positive_stage_cap_not_lowered", score=_score(user.get("relationship_score"))) if is_owner_exclusive(user): return _result(False, "owner_exclusive_exempt", score=_score(user.get("relationship_score"))) before = _score(user.get("relationship_score")) if before <= 0: return _result(False, "non_positive_score_exempt", score=before) if new_max >= old_max: return _result(False, "positive_stage_cap_not_lowered", score=before) transition = f"{old_key}->{new_key}" marker = user.get("relationship_positive_stage_cap_migration") if isinstance(marker, dict) and marker.get("transition") == transition: return _result(False, "positive_stage_cap_already_migrated", score=before) after = min(new_max, int(round(before / old_max * new_max))) user["relationship_positive_stage_cap_migration"] = { "transition": transition, "old_cap_key": old_key, "new_cap_key": new_key, "old_cap_max": old_max, "new_cap_max": new_max, "migrated_at": _timestamp(now), } if after >= before: return _result(False, "positive_stage_cap_no_score_drop", score=before) user["relationship_score"] = after result = _append_cap_audit_entry( user, before=before, after=after, now=now, reason_code="relationship_positive_stage_cap_migration", metadata={ "old_cap_key": old_key, "new_cap_key": new_key, "old_cap_max": old_max, "new_cap_max": new_max, "transition": transition, }, ) result["code"] = "positive_stage_cap_migrated" return result def apply_natural_relationship_decay( user: Any, *, now: Any = None, policy: Any = None, grace_days: int = DEFAULT_DECAY_GRACE_DAYS, early_rate: int = 2, middle_rate: int = 5, late_rate: int = 8, ) -> dict[str, Any]: """Idempotently decay positive scores toward zero by inactive calendar day.""" if not isinstance(user, dict): return _result(False, "invalid_user") ts = _timestamp(now) if is_owner_exclusive(user): return _result(False, "owner_exclusive_frozen", score=_score(user.get("relationship_score"))) score = _score(user.get("relationship_score")) if score <= 0: return _result(False, "non_positive_score", score=score) last_effective = _finite_number(user.get("relationship_last_effective_at")) if not last_effective: last_effective = _finite_number(user.get("last_activity_at")) or _finite_number(user.get("last_seen")) if not last_effective or ts <= last_effective: return _result(False, "no_inactive_window", score=score) today = datetime.fromtimestamp(ts, tz=timezone.utc).date() last_day = datetime.fromtimestamp(last_effective, tz=timezone.utc).date() inactive_days = max(0, (today - last_day).days) grace = max(0, min(30, int(grace_days or 0))) if inactive_days <= grace: return _result(False, "within_grace", score=score) settled_text = str(user.get("relationship_decay_settled_day") or "").strip() try: settled_day = datetime.fromisoformat(settled_text).date() if settled_text else last_day except ValueError: settled_day = last_day start_offset = max(grace + 1, (settled_day - last_day).days + 1) if start_offset > inactive_days: return _result(False, "already_settled", score=score) rates = ( max(0, min(30, int(early_rate or 0))), max(0, min(30, int(middle_rate or 0))), max(0, min(30, int(late_rate or 0))), ) requested = sum(_decay_for_inactive_day(day, rates=rates) for day in range(start_offset, inactive_days + 1)) if requested <= 0: user["relationship_decay_settled_day"] = today.isoformat() return _result(False, "no_decay", score=score) before_projection = relationship_stage_for_score(score, policy) candidate = max(0, score - requested) candidate = _apply_stage_hysteresis(user, score, candidate, ts, policy, before_projection) applied = score - candidate user["relationship_decay_settled_day"] = today.isoformat() if applied <= 0: return _result(False, "stage_hysteresis", score=score) user["relationship_score"] = candidate ledger = user.setdefault("relationship_ledger", []) if not isinstance(ledger, list): ledger = [] user["relationship_ledger"] = ledger entry = { "event_key": f"natural_decay:{today.isoformat()}", "reason_code": "natural_decay", "delta": -applied, "score_before": score, "score_after": candidate, "created_at": ts, "inactive_days": inactive_days, } ledger.append(entry) if len(ledger) > 200: del ledger[:-200] return _result(True, "applied", score=candidate, delta=-applied, entry=deepcopy(entry)) def relationship_ledger_summary(user: Any, *, limit: int = 12) -> dict[str, Any]: if not isinstance(user, dict): return {"items": [], "trend": "unknown"} ledger = user.get("relationship_ledger") items = [deepcopy(item) for item in ledger if isinstance(item, dict)] if isinstance(ledger, list) else [] recent = items[-max(1, min(50, int(limit or 12))):] total = sum(_integer(item.get("delta")) or 0 for item in recent) trend = "rising" if total > 0 else "cooling" if total < 0 else "steady" return {"items": recent, "trend": trend, "recent_delta": total} def record_manual_relationship_change( user: Any, before: Any, after: Any, *, now: Any = None, reason_code: Any = "administrator_manual", ) -> dict[str, Any]: """Record an already-authorized exact admin adjustment without re-settling it.""" if not isinstance(user, dict): return _result(False, "invalid_user") before_score = _score(before) after_score = _score(after) if before_score == after_score: return _result(False, "unchanged", score=after_score) ts = _timestamp(now) reason = _reason(reason_code) or "administrator_manual" ledger = user.setdefault("relationship_ledger", []) if not isinstance(ledger, list): ledger = [] user["relationship_ledger"] = ledger entry = { "event_key": _event_key(reason, ts, f"manual:{ts}:{before_score}:{after_score}", 60), "reason_code": reason, "delta": after_score - before_score, "score_before": before_score, "score_after": after_score, "created_at": ts, "source": "administrator", } ledger.append(entry) if len(ledger) > 200: del ledger[:-200] user["relationship_last_effective_at"] = ts user["relationship_decay_settled_day"] = "" return _result(True, "recorded", score=after_score, delta=after_score - before_score, entry=deepcopy(entry)) def _append_cap_audit_entry( user: dict[str, Any], *, before: int, after: int, now: Any, reason_code: Any, metadata: dict[str, Any], ) -> dict[str, Any]: ts = _timestamp(now) reason = _reason(reason_code) or "relationship_positive_stage_cap_runtime_clamp" ledger = user.setdefault("relationship_ledger", []) if not isinstance(ledger, list): ledger = [] user["relationship_ledger"] = ledger entry = { "event_key": _event_key(reason, ts, f"{reason}:{before}:{after}:{metadata}", 60), "reason_code": reason, "delta": after - before, "score_before": before, "score_after": after, "created_at": ts, "source": "relationship_cap", **metadata, } ledger.append(entry) if len(ledger) > 200: del ledger[:-200] return _result(True, reason, score=after, delta=after - before, entry=deepcopy(entry)) def _apply_stage_hysteresis(user: dict[str, Any], before: int, candidate: int, ts: float, policy: Any, before_projection: dict[str, Any]) -> int: after_projection = relationship_stage_for_score(candidate, policy) before_index = int(before_projection.get("stage_index") or 0) after_index = int(after_projection.get("stage_index") or 0) if after_index >= before_index: return candidate stages = normalize_relationship_stage_policy(policy) last_drop = _finite_number(user.get("relationship_last_decay_stage_drop_at")) or 0.0 if last_drop and ts - last_drop < 7 * 86400: current_min = int(stages[before_index]["min"]) return max(candidate, current_min) immediate_index = max(0, before_index - 1) limited = max(candidate, int(stages[immediate_index]["min"])) if relationship_stage_for_score(limited, policy).get("stage_index") < before_index: user["relationship_last_decay_stage_drop_at"] = ts return limited def _decay_for_inactive_day(day: int, *, rates: tuple[int, int, int] = (2, 5, 8)) -> int: configured = ((7, rates[0]), (14, rates[1]), (10**9, rates[2])) for maximum, amount in configured: if day <= maximum: return amount return rates[2] def _event_key(reason: str, ts: float, event_id: Any, window_seconds: int) -> str: explicit = str(event_id or "").strip() source = explicit[:160] if explicit else f"{reason}:{int(ts // window_seconds)}" return sha256(source.encode("utf-8", errors="ignore")).hexdigest()[:24] def _reason(value: Any) -> str: text = "_".join(str(value or "").strip().lower().split()) return "".join(ch for ch in text if ch.isalnum() or ch in {"_", "-"})[:48] def _score(value: Any) -> int: parsed = _integer(value) return max(RELATIONSHIP_SCORE_MIN, min(RELATIONSHIP_SCORE_MAX, parsed if parsed is not None else 0)) def _integer(value: Any) -> int | None: if isinstance(value, bool): return None if isinstance(value, int): return value if isinstance(value, float) and isfinite(value): return int(value) if isinstance(value, str): try: return int(value.strip()) except ValueError: return None return None def _finite_number(value: Any) -> float | None: if isinstance(value, bool) or not isinstance(value, (int, float)): return None number = float(value) return number if isfinite(number) else None def _timestamp(value: Any) -> float: number = _finite_number(value) return number if number is not None and number > 0 else datetime.now(tz=timezone.utc).timestamp() def _bounded_int(value: Any, default: int, minimum: int, maximum: int) -> int: parsed = _integer(value) return max(minimum, min(maximum, parsed if parsed is not None else default)) def _result(changed: bool, code: str, *, score: int | None = None, delta: int = 0, entry: dict[str, Any] | None = None) -> dict[str, Any]: result: dict[str, Any] = {"changed": bool(changed), "code": code, "delta": int(delta)} if score is not None: result["score"] = int(score) if entry is not None: result["entry"] = entry return result __all__ = [ "OWNER_EXCLUSIVE_MODE", "NORMAL_RELATIONSHIP_MODE", "apply_natural_relationship_decay", "apply_relationship_event", "clamp_relationship_positive_stage_cap", "is_owner_exclusive", "migrate_relationship_positive_stage_cap", "normalize_relationship_mode", "normalize_relationship_positive_stage_cap_key", "record_manual_relationship_change", "relationship_positive_score_cap", "relationship_ledger_summary", ]