From ffee444f467a24fa3b20f61eb9117ada89fe32a6 Mon Sep 17 00:00:00 2001 From: Codex Local Date: Thu, 30 Jul 2026 03:09:53 +0800 Subject: [PATCH] feat(c2): add unified person and context projection --- context_orchestration.py | 154 +++++++++ core_store.py | 3 + main.py | 238 ++++++++++++++ memory_companion_adapter.py | 56 ++++ p4_shadow.py | 159 ++++++++++ person_context_contract.py | 421 +++++++++++++++++++++++++ tests/test_c2_context_orchestration.py | 77 +++++ tests/test_c2_dual_plugin_link.py | 91 ++++++ tests/test_c2_unified_person.py | 69 ++++ unified_person_registry.py | 284 +++++++++++++++++ 10 files changed, 1552 insertions(+) create mode 100644 context_orchestration.py create mode 100644 p4_shadow.py create mode 100644 person_context_contract.py create mode 100644 tests/test_c2_context_orchestration.py create mode 100644 tests/test_c2_dual_plugin_link.py create mode 100644 tests/test_c2_unified_person.py create mode 100644 unified_person_registry.py diff --git a/context_orchestration.py b/context_orchestration.py new file mode 100644 index 0000000..53652a5 --- /dev/null +++ b/context_orchestration.py @@ -0,0 +1,154 @@ +"""Chat-side P3 context orchestration. + +This module is deliberately a read-only coordinator. It creates a bounded +projection for the companion runtime; it does not alter the normal response +path, sinks, or any persistent person store. +""" +from __future__ import annotations + +from copy import deepcopy +from typing import Any + +try: # package import + from .person_context_contract import ( + P3_CONTRACT_NAME, + P3_CONTRACT_VERSION, + P3_SLOT_NAMES, + P3_SLOT_OWNERS, + build_context_projection, + make_context_slot, + merge_context_slots, + validate_context_projection, + validate_context_slot, + ) +except ImportError: # direct test/import fallback + from person_context_contract import ( # type: ignore + P3_CONTRACT_NAME, + P3_CONTRACT_VERSION, + P3_SLOT_NAMES, + P3_SLOT_OWNERS, + build_context_projection, + make_context_slot, + merge_context_slots, + validate_context_projection, + validate_context_slot, + ) + + +_GROUP_KEYS = frozenset({ + "group", "group_id", "group_name", "group_member", "group_members", + "member", "members", "群", "群聊", "群成员", "群信息", +}) + + +def _as_mapping(value: Any) -> dict[str, Any]: + return deepcopy(value) if isinstance(value, dict) else {} + + +def _contains_group_fact(value: Any) -> bool: + if isinstance(value, dict): + return any(str(key).strip().lower() in _GROUP_KEYS for key in value) or any( + _contains_group_fact(item) for item in value.values() + ) + if isinstance(value, (list, tuple)): + return any(_contains_group_fact(item) for item in value) + return False + + +def _slot_payload(name: str, value: Any) -> tuple[dict[str, Any], list[str]]: + payload = _as_mapping(value) + warnings: list[str] = [] + if name == "person" and _contains_group_fact(payload): + return {}, ["person_group_domain_mixed"] + return payload, warnings + + +def _make_slot(name: str, value: Any, *, revision: int, bridge_available: bool) -> dict[str, Any]: + payload, warnings = _slot_payload(name, value) + if not bridge_available: + return make_context_slot( + name, payload, revision=revision, state="degraded", + warnings=warnings + ["bridge_unavailable"], + ) + if name == "person" and warnings: + return make_context_slot(name, {}, revision=revision, state="invalid", warnings=warnings) + return make_context_slot(name, payload, revision=revision, state="ready", warnings=warnings) + + +def build_context( + slots: dict[str, Any] | None = None, + *, + persona: dict[str, Any] | None = None, + runtime: dict[str, Any] | None = None, + person: dict[str, Any] | None = None, + scene: dict[str, Any] | None = None, + revisions: dict[str, int] | None = None, + bridge_available: bool = True, + existing: dict[str, Any] | None = None, + warnings: list[str] | None = None, +) -> dict[str, Any]: + """Build a four-slot P3 projection without exposing raw conversation data. + + ``slots`` is accepted for callers that already have a slot map. Explicit + keyword values take precedence when supplied. Existing projections are + merged by slot and revision, so replaying an identical event is harmless. + """ + provided = _as_mapping(slots) + explicit = {"persona": persona, "runtime": runtime, "person": person, "scene": scene} + for name, value in explicit.items(): + if value is not None: + provided[name] = value + revision_map = revisions if isinstance(revisions, dict) else {} + built: dict[str, dict[str, Any]] = {} + for name in P3_SLOT_NAMES: + revision = revision_map.get(name, 1) + try: + revision = max(1, int(revision)) + except (TypeError, ValueError): + revision = 1 + built[name] = _make_slot( + name, provided.get(name, {}), revision=revision, + bridge_available=bridge_available, + ) + missing_bridge_context = not provided + state = "degraded" if not bridge_available else ("legacy_local" if missing_bridge_context else "ready") + if missing_bridge_context and bridge_available: + for slot in built.values(): + slot["state"] = "legacy_local" + slot["warnings"] = list(slot.get("warnings") or []) + ["p3_context_missing"] + result = build_context_projection( + built, state=state, revision=max([slot["revision"] for slot in built.values()], default=1), + warnings=list(warnings or []) + (["bridge_unavailable"] if not bridge_available else (["p3_context_missing"] if missing_bridge_context else [])), + ) + if existing is not None: + result = merge_context_slots(existing, result) + return result + + +def project_context(context: Any, *, bridge_available: bool = True) -> dict[str, Any]: + """Return a defensive P3 projection, degrading rather than trusting bad input.""" + if not isinstance(context, dict): + return build_context(bridge_available=bridge_available, warnings=["context_invalid"]) + candidate = deepcopy(context) + errors = validate_context_projection(candidate) + if errors: + return build_context( + bridge_available=False, + warnings=["context_rejected"] + errors[:8], + ) + if not bridge_available: + candidate["state"] = "degraded" + candidate["warnings"] = list(candidate.get("warnings") or []) + ["bridge_unavailable"] + return candidate + + +def validate_context(context: Any) -> list[str]: + """Expose the shared contract validator as the orchestration API.""" + return validate_context_projection(context) + + +__all__ = [ + "P3_CONTRACT_NAME", "P3_CONTRACT_VERSION", "P3_SLOT_NAMES", "P3_SLOT_OWNERS", + "build_context", "project_context", "validate_context", "build_context_projection", + "make_context_slot", "merge_context_slots", "validate_context_slot", +] diff --git a/core_store.py b/core_store.py index 6b347ef..267adeb 100644 --- a/core_store.py +++ b/core_store.py @@ -116,6 +116,7 @@ from .helpers import ( ) from .config_migration import _ensure_config_parent_dir from .storage.store_manager import StoreManager +from .person_context_contract import empty_person_store, ensure_person_store from .planning import ( build_daily_plan_prompt, build_detail_enhancement_prompt, @@ -392,6 +393,7 @@ class CoreStoreMixin: "personal_goal_state": {}, "personal_goals": [], "food_menu": {}, + "unified_person": empty_person_store(), } @staticmethod @@ -457,6 +459,7 @@ class CoreStoreMixin: data.setdefault("personal_goal_state", {}) data.setdefault("personal_goals", []) data.setdefault("food_menu", {}) + ensure_person_store(data) return data @staticmethod diff --git a/main.py b/main.py index 8e8c69c..a878b64 100644 --- a/main.py +++ b/main.py @@ -123,6 +123,17 @@ from .helpers import ( ) from .config_migration import migrate_flat_config_into_schema_groups from .bot_personal_contract import capability_descriptor, contract_self_check +from .person_context_contract import ( + CONTRACT_NAME as PERSON_CONTRACT_NAME, + CONTRACT_VERSION as PERSON_CONTRACT_VERSION, + P3_CONTRACT_NAME, + P3_CONTRACT_VERSION, + build_identity_key, + contract_self_check as person_contract_self_check, +) +from .unified_person_registry import UnifiedPersonRegistry +from .context_orchestration import build_context, project_context +from .p4_shadow import build_p4_shadow from .plugin_identity import ( PLUGIN_ID, PLUGIN_VERSION, @@ -361,6 +372,27 @@ class PrivateCompanionExtensionAPI: }, } + def get_unified_person_contract(self) -> dict[str, Any]: + return self._plugin.unified_person_contract_status() + + def resolve_unified_person(self, identity: dict[str, Any]) -> dict[str, Any]: + return self._plugin.resolve_unified_person_identity(identity) + + def create_unified_person( + self, + identity: dict[str, Any], + *, + profile: dict[str, Any] | None = None, + operation_id: str = "", + ) -> dict[str, Any]: + return self._plugin.create_unified_person(identity, profile=profile, operation_id=operation_id) + + def get_unified_person_projection(self, person_id: str) -> dict[str, Any] | None: + return self._plugin.get_unified_person_projection(person_id) + + def get_unified_person_context(self, event: Any | None = None) -> dict[str, Any]: + return self._plugin.build_unified_person_context(event) + def get_scene_context(self, user_id: str = "") -> dict[str, Any]: """Return the current structured Bot-life context for plugin integrations.""" plugin = self._plugin @@ -2184,6 +2216,7 @@ class PrivateCompanionPlugin( self._qzone_last_bot = None startup_load_started = time.perf_counter() self.data = self._load_data_sync() + self.unified_person_registry = UnifiedPersonRegistry(self.data) self._apply_tts_runtime_overrides() load_elapsed_ms = int((time.perf_counter() - startup_load_started) * 1000) if load_elapsed_ms > 1200: @@ -2201,6 +2234,211 @@ class PrivateCompanionPlugin( def bot_personal_capability_status(self) -> dict[str, Any]: return dict(self.bot_personal_capabilities) + def unified_person_contract_status(self) -> dict[str, Any]: + issues = list(person_contract_self_check()) + return { + "available": not issues, + "state": "ready" if not issues else "degraded", + "degraded": bool(issues), + "contract_name": PERSON_CONTRACT_NAME, + "contract_version": PERSON_CONTRACT_VERSION, + "p3_contract_name": P3_CONTRACT_NAME, + "p3_contract_version": P3_CONTRACT_VERSION, + "warnings": issues, + "registry": self.unified_person_registry.status(), + } + + def _unified_person_event_identity( + self, + event: Any | None = None, + *, + subject_id: str = "", + subject_namespace: str = "", + ) -> dict[str, str]: + sender_id = _single_line(subject_id, 160) + if not sender_id and event is not None: + sender_getter = getattr(self, "_event_sender_id", None) + if callable(sender_getter): + try: + sender_id = _single_line(sender_getter(event), 160) + except Exception: + sender_id = "" + if not sender_id: + try: + sender_id = _single_line(event.get_sender_id(), 160) + except Exception: + sender_id = "" + platform = "" + if event is not None: + try: + platform = _single_line(event.get_platform_name(), 80) + except Exception: + platform = "" + if not platform: + platform = _single_line(str(getattr(event, "unified_msg_origin", "") or "").split(":", 1)[0], 80) + platform = platform or _single_line(getattr(self, "target_platform", ""), 80) or "unknown" + self_id = "" + if event is not None: + self_getter = getattr(self, "_event_self_id", None) + if callable(self_getter): + try: + self_id = _single_line(self_getter(event), 160) + except Exception: + self_id = "" + if not self_id: + ids = sorted(_single_line(item, 160) for item in self._known_bot_self_ids() if _single_line(item, 160)) + if len(ids) == 1: + self_id = ids[0] + if not sender_id or not self_id: + return {} + namespace = _single_line(subject_namespace, 160).lower() + if not namespace: + namespace = f"{platform}:bot" if sender_id == self_id else f"{platform}:user" + adapter_instance = _single_line( + getattr(event, "adapter_instance_id", "") if event is not None else "", + 160, + ) or f"{platform}:{_single_line(getattr(self, 'target_platform', ''), 80) or platform}" + return { + "companion_instance_id": PLUGIN_ID, + "bot_account_id": f"{platform}:{self_id}", + "adapter_instance_id": adapter_instance, + "subject_namespace": namespace, + "platform_subject_id": sender_id, + } + + def resolve_unified_person_identity(self, identity: dict[str, Any]) -> dict[str, Any]: + return self.unified_person_registry.resolve(identity) + + def create_unified_person( + self, + identity: dict[str, Any], + *, + profile: dict[str, Any] | None = None, + operation_id: str = "", + ) -> dict[str, Any]: + return self.unified_person_registry.create_or_link( + identity, + profile=profile, + operation_id=operation_id, + actor_id="companion", + ) + + def get_unified_person_projection(self, person_id: str) -> dict[str, Any] | None: + return self.unified_person_registry.read_projection(person_id) + + def resolve_unified_person_for_event(self, event: Any | None = None) -> dict[str, Any]: + identity = self._unified_person_event_identity(event) + if not identity: + return {"state": "pending", "identity_key": "", "person_id": "", "errors": ["event_identity_missing"]} + return self.resolve_unified_person_identity(identity) + + def create_unified_person_for_event( + self, + event: Any | None = None, + *, + operation_id: str = "", + profile: dict[str, Any] | None = None, + ) -> dict[str, Any]: + identity = self._unified_person_event_identity(event) + if not identity: + return {"ok": False, "state": "pending", "code": "event_identity_missing", "person_id": ""} + try: + identity_key = build_identity_key(identity) + except (TypeError, ValueError): + return {"ok": False, "state": "invalid", "code": "identity_invalid", "person_id": ""} + user_profile = dict(profile) if isinstance(profile, dict) else {} + if event is not None and not user_profile.get("display_name"): + name_getter = getattr(self, "_sender_display_name", None) + if callable(name_getter): + try: + user_profile["display_name"] = _single_line(name_getter(event), 80) + except Exception: + pass + return self.create_unified_person( + identity, + profile=user_profile, + operation_id=operation_id or f"companion.person.create:{identity_key[-24:]}", + ) + + def build_unified_person_context(self, event: Any | None = None) -> dict[str, Any]: + identity = self._unified_person_event_identity(event) + resolution = self.resolve_unified_person_identity(identity) if identity else { + "state": "pending", "identity_key": "", "person_id": "", "errors": ["event_identity_missing"], + } + state = str(resolution.get("state") or "pending") + projection = resolution.get("projection") if isinstance(resolution.get("projection"), dict) else None + scope = "unknown" + if event is not None: + try: + scope = "private" if bool(event.is_private_chat()) else "group" + except Exception: + scope = "unknown" + platform = str(identity.get("subject_namespace") or "").split(":", 1)[0] if identity else "" + group_id = "" + if scope == "group": + group_getter = getattr(self, "_extract_group_id_from_event", None) + if callable(group_getter): + try: + group_id = _single_line(group_getter(event), 160) + except Exception: + group_id = "" + group_scope = f"{platform}:group:{group_id}" if platform and group_id else "" + group_overlay = None + if state == "resolved" and group_scope and resolution.get("person_id"): + group_overlay = self.unified_person_registry.read_group_overlay( + str(resolution.get("person_id") or ""), group_scope + ) + person_payload = { + key: projection.get(key) + for key in ( + "person_id", "identity_assurance", "profile_status", "relation_policy_id", + "relation_label", "owner_mode", "affinity_band", "projection_revision", + "group_overlay_ref", + ) + if projection is not None and projection.get(key) not in (None, "", [], {}) + } + p3 = build_context( + persona={"companion_instance_id": PLUGIN_ID}, + runtime={"platform": platform, "scope": scope, "adapter_instance_id": identity.get("adapter_instance_id", "")}, + person=person_payload, + scene={ + "scope": scope, + "group_scope": group_scope, + "group_id_present": bool(group_id), + "group_overlay_revision": group_overlay.get("revision") if isinstance(group_overlay, dict) else 0, + }, + bridge_available=True, + ) + if state != "resolved": + p3["state"] = state if state in {"pending", "invalid", "degraded", "legacy_local"} else "degraded" + p3["warnings"] = list(p3.get("warnings") or []) + list(resolution.get("errors") or [f"person_{state}"])[:8] + person_slot = p3.get("slots", {}).get("person") + if isinstance(person_slot, dict): + person_slot["state"] = p3["state"] + p3 = project_context(p3) + p4 = build_p4_shadow( + source_kind="companion", + target_kind="memory_bridge", + authority="companion", + reason_code="projection_ready" if state == "resolved" else f"person_{state}", + safe_reference=str(resolution.get("person_id") or ""), + operation_id=f"person.context:{str(resolution.get('identity_key') or 'pending')[-24:]}", + status="shadow" if state == "resolved" else "degraded", + ) + return { + "contract_name": PERSON_CONTRACT_NAME, + "contract_version": PERSON_CONTRACT_VERSION, + "p3_contract_name": P3_CONTRACT_NAME, + "p3_contract_version": P3_CONTRACT_VERSION, + "state": state, + "identity": {"identity_key": str(resolution.get("identity_key") or ""), "person_id": str(resolution.get("person_id") or "")}, + "projection": projection, + "p3": p3, + "p4_shadow": p4, + "scope": scope, + "group_scope": group_scope, + } + def _sqlite_wal_candidate_paths(self) -> list[Path]: data_root = Path(get_astrbot_data_path()) candidates = [ diff --git a/memory_companion_adapter.py b/memory_companion_adapter.py index 69f1184..be27aaf 100644 --- a/memory_companion_adapter.py +++ b/memory_companion_adapter.py @@ -1083,6 +1083,7 @@ class MemoryCompanionAdapterMixin: ) -> None: payload = self._memory_companion_build_private_context(user_id=user_id, user=user, text=text, event=event) self._memory_companion_attach_context(event, payload) + self._memory_companion_attach_person_context(event) def _memory_companion_attach_group_context( self, @@ -1103,6 +1104,61 @@ class MemoryCompanionAdapterMixin: event=event, ) self._memory_companion_attach_context(event, payload) + self._memory_companion_attach_person_context(event) + + def _memory_companion_attach_person_context(self, event: Any | None) -> None: + """Attach only validated person/P3 references to the event carrier.""" + if event is None: + return + builder = getattr(self, "build_unified_person_context", None) + if not callable(builder): + return + try: + context = builder(event) + except Exception as exc: + logger.debug("[PrivateCompanion] Unified Person 上下文生成失败: %s", _single_line(exc, 160)) + return + if not isinstance(context, dict): + return + identity = context.get("identity") if isinstance(context.get("identity"), dict) else {} + projection = context.get("projection") if isinstance(context.get("projection"), dict) else None + p3 = dict(context.get("p3")) if isinstance(context.get("p3"), dict) else None + if p3 is not None: + p3["person_id"] = _single_line(identity.get("person_id"), 120) + p3["scope"] = _single_line(context.get("scope"), 40) + bridge = self._memory_companion_bridge() + person_result: dict[str, Any] = {"state": context.get("state", "pending"), "read_only": True} + context_result: dict[str, Any] = {"state": "legacy_local", "read_only": True} + if bridge is not None: + consumer = getattr(bridge, "consume_person_projection", None) + if callable(consumer) and projection is not None: + person_result = consumer( + projection, + expected_identity_key=_single_line(identity.get("identity_key"), 180), + expected_person_id=_single_line(identity.get("person_id"), 120), + ) + context_consumer = getattr(bridge, "consume_context_projection", None) + if callable(context_consumer) and p3 is not None: + context_result = context_consumer( + p3, + expected_person_id=_single_line(identity.get("person_id"), 120), + expected_scope=_single_line(context.get("scope"), 40), + ) + safe_payload = { + "state": _single_line(context.get("state"), 40) or "pending", + "identity": { + "identity_key": _single_line(identity.get("identity_key"), 180), + "person_id": _single_line(identity.get("person_id"), 120), + }, + "projection": person_result.get("projection_ref") if isinstance(person_result, dict) else None, + "context": context_result.get("context_ref") if isinstance(context_result, dict) else None, + "p4_shadow": context.get("p4_shadow") if isinstance(context.get("p4_shadow"), dict) else {}, + } + try: + setattr(event, "person_context_projection", safe_payload) + except Exception: + pass + self._memory_companion_attach_context(event, {"unified_person": safe_payload}) async def _memory_companion_record_proactive_message( self, diff --git a/p4_shadow.py b/p4_shadow.py new file mode 100644 index 0000000..edb1903 --- /dev/null +++ b/p4_shadow.py @@ -0,0 +1,159 @@ +"""Metadata-only P4 shadow records for the chat-side companion. + +P4 records are advisory telemetry. They cannot execute policy or influence a +normal chat response, and unsafe request content is never copied into them. +""" +from __future__ import annotations + +from datetime import datetime, timezone +import hashlib +import json +import re +from typing import Any + + +SHADOW_SCHEMA_VERSION = "chat.p4.shadow.v1" +_IDENTIFIER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,119}$") +_FORBIDDEN = frozenset({ + "raw_prompt", "prompt", "text", "content", "chat_text", "messages", + "transcript", "private_object", "private_object_ref", "database", "db", +}) +_ALLOWED_STATUS = frozenset({"shadow", "invalid", "degraded"}) + + +def _now() -> str: + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +def _safe_id(value: Any, field: str) -> str: + if not isinstance(value, str) or not _IDENTIFIER.fullmatch(value): + raise ValueError(f"{field}_invalid") + return value + + +def _canonical(value: Any) -> str: + return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + + +def _has_forbidden(value: Any) -> bool: + if isinstance(value, dict): + return any(str(key).strip().lower() in _FORBIDDEN for key in value) or any( + _has_forbidden(item) for item in value.values() + ) + if isinstance(value, (list, tuple)): + return any(_has_forbidden(item) for item in value) + return False + + +def _safe_hash(value: Any) -> str: + return "sha256:" + hashlib.sha256(_canonical(value).encode("utf-8")).hexdigest() + + +def build_p4_shadow( + *, + source_kind: Any, + target_kind: Any, + authority: Any, + reason_code: Any, + safe_reference: Any = "", + safe_hash: Any = "", + event_id: Any = "", + operation_id: Any = "", + timestamp: Any = None, + status: Any = "shadow", + metadata: dict[str, Any] | None = None, +) -> dict[str, Any]: + """Build a safe P4 record; malformed input becomes an explicit invalid record.""" + errors: list[str] = [] + raw_metadata = metadata if isinstance(metadata, dict) else {} + try: + if _has_forbidden(raw_metadata): + raise ValueError("forbidden_metadata") + source = _safe_id(source_kind, "source_kind") + target = _safe_id(target_kind, "target_kind") + auth = _safe_id(authority, "authority") + reason = _safe_id(reason_code, "reason_code") + reference = "" if safe_reference in (None, "") else _safe_id(safe_reference, "safe_reference") + digest = str(safe_hash or "") + if digest and not re.fullmatch(r"sha256:[0-9a-f]{64}", digest): + raise ValueError("safe_hash_invalid") + event = _safe_id(event_id, "event_id") if event_id else "" + operation = _safe_id(operation_id, "operation_id") if operation_id else "" + if not event and not operation: + raise ValueError("event_or_operation_required") + state = status if status in _ALLOWED_STATUS else "invalid" + record = { + "schema_version": SHADOW_SCHEMA_VERSION, + "source_kind": source, + "target_kind": target, + "authority": auth, + "reason_code": reason, + "safe_reference": reference, + "safe_hash": digest or _safe_hash({"source_kind": source, "target_kind": target, "reason_code": reason}), + "event_id": event, + "operation_id": operation, + "timestamp": str(timestamp or _now()), + "status": state, + "shadow_only": True, + } + return record + except (TypeError, ValueError) as exc: + errors.append(str(exc) or "invalid_input") + return { + "schema_version": SHADOW_SCHEMA_VERSION, + "source_kind": "invalid", + "target_kind": "invalid", + "authority": "invalid", + "reason_code": "invalid_input", + "safe_reference": "", + "safe_hash": "", + "event_id": "", + "operation_id": "invalid_input", + "timestamp": _now(), + "status": "invalid", + "shadow_only": True, + "errors": errors[:8], + } + + +def validate_p4_shadow(value: Any) -> list[str]: + if not isinstance(value, dict): + return ["shadow_invalid"] + errors: list[str] = [] + required = ("schema_version", "source_kind", "target_kind", "authority", "reason_code", "safe_reference", "safe_hash", "event_id", "operation_id", "timestamp", "status", "shadow_only") + errors.extend(f"missing_{key}" for key in required if key not in value) + if errors: + return errors + if value.get("schema_version") != SHADOW_SCHEMA_VERSION: + errors.append("schema_version_mismatch") + for field in ("source_kind", "target_kind", "authority", "reason_code"): + if not isinstance(value.get(field), str) or not _IDENTIFIER.fullmatch(value[field]): + errors.append(f"{field}_invalid") + if value.get("safe_reference") and (not isinstance(value["safe_reference"], str) or not _IDENTIFIER.fullmatch(value["safe_reference"])): + errors.append("safe_reference_invalid") + if not isinstance(value.get("safe_hash"), str) or (value["safe_hash"] and not re.fullmatch(r"sha256:[0-9a-f]{64}", value["safe_hash"])): + errors.append("safe_hash_invalid") + if not isinstance(value.get("event_id"), str) or not isinstance(value.get("operation_id"), str) or not (value["event_id"] or value["operation_id"]): + errors.append("event_or_operation_invalid") + if value.get("status") not in _ALLOWED_STATUS: + errors.append("status_invalid") + if value.get("shadow_only") is not True: + errors.append("shadow_only_required") + if _has_forbidden(value): + errors.append("forbidden_field") + return sorted(set(errors)) + + +def project_p4_shadow(value: Any) -> dict[str, Any]: + candidate = dict(value) if isinstance(value, dict) else {} + errors = validate_p4_shadow(candidate) + if errors: + return build_p4_shadow( + source_kind="invalid", target_kind="invalid", authority="invalid", + reason_code="projection_rejected", operation_id="invalid_projection", + status="invalid", + ) | {"errors": errors[:8]} + return dict(candidate) + + +__all__ = ["SHADOW_SCHEMA_VERSION", "build_p4_shadow", "validate_p4_shadow", "project_p4_shadow"] diff --git a/person_context_contract.py b/person_context_contract.py new file mode 100644 index 0000000..ba78f32 --- /dev/null +++ b/person_context_contract.py @@ -0,0 +1,421 @@ +from __future__ import annotations + +from datetime import datetime, timezone +import hashlib +import json +import re +import unicodedata +from typing import Any + + +CONTRACT_NAME = "chat.unified_person.v1" +CONTRACT_VERSION = "1.0" +PROJECTION_SCHEMA_VERSION = "1.0" +P3_CONTRACT_NAME = "chat.p3.context.v1" +P3_CONTRACT_VERSION = "1.0" +P3_SLOT_NAMES = ("persona", "runtime", "person", "scene") +P3_SLOT_OWNERS = { + "persona": "companion", + "runtime": "companion", + "person": "memory_projection", + "scene": "companion", +} +P3_SLOT_STATES = frozenset({"ready", "legacy_local", "invalid", "degraded", "pending"}) +IDENTITY_FIELDS = ( + "companion_instance_id", + "bot_account_id", + "adapter_instance_id", + "subject_namespace", + "platform_subject_id", +) +PROJECTION_FIELDS = ( + "contract_name", + "contract_version", + "contract_fingerprint", + "projection_schema_version", + "projection_revision", + "person_id", + "resolved_identity_key", + "identity_assurance", + "profile_status", + "display_name", + "aliases", + "relation_policy_id", + "relation_label", + "owner_mode", + "affinity_score", + "affinity_band", + "relationship_capabilities", + "group_overlay_ref", + "updated_at", +) +IDENTITY_ASSURANCE_VALUES = frozenset({"unverified", "observed", "verified", "explicit_linked"}) +PROFILE_STATUS_VALUES = frozenset({"active", "suspended", "quarantined", "deleted"}) +OWNER_MODE_VALUES = frozenset({"none", "owner", "not_owner"}) +AFFINITY_BAND_VALUES = frozenset({"critical", "guarded", "neutral", "positive"}) +RELATIONSHIP_CAPABILITIES = frozenset( + { + "comfort", + "proactive_care", + "joking", + "affectionate_address", + "missing_you", + "romantic_expression", + } +) +CONTEXT_FORBIDDEN_KEYS = frozenset( + { + "raw_prompt", + "prompt", + "private_object", + "private_object_ref", + "object", + "chat_text", + "content", + "messages", + "transcript", + "database", + } +) + + +def _canonical(value: Any) -> str: + return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + + +def _text(value: Any, field: str, limit: int = 160) -> str: + if isinstance(value, bool) or not isinstance(value, (str, int)): + raise ValueError(f"{field}_invalid") + text = unicodedata.normalize("NFC", str(value)).strip() + if not text or "\x00" in text or len(text) > limit: + raise ValueError(f"{field}_invalid") + return text + + +def canonical_identity(identity: dict[str, Any]) -> dict[str, str]: + if not isinstance(identity, dict): + raise ValueError("identity_invalid") + result = {field: _text(identity.get(field), field) for field in IDENTITY_FIELDS} + result["subject_namespace"] = result["subject_namespace"].lower() + return result + + +def build_identity_key(identity: dict[str, Any]) -> str: + digest = hashlib.sha256(_canonical(canonical_identity(identity)).encode("utf-8")).hexdigest() + return f"chat-origin-v1:{digest}" + + +def person_id_for_identity(identity: dict[str, Any]) -> str: + return f"person_{hashlib.sha256(build_identity_key(identity).encode('utf-8')).hexdigest()[:24]}" + + +def affinity_band(score: Any) -> str: + try: + value = int(score) + except (TypeError, ValueError): + value = 0 + if value <= -800: + return "critical" + if value < 0: + return "guarded" + if value == 0: + return "neutral" + return "positive" + + +def _now() -> str: + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +def empty_person_store() -> dict[str, Any]: + return { + "version": 1, + "profiles": {}, + "identity_links": {}, + "group_overlays": {}, + "relation_policies": { + "default_friend": { + "label": "friend", + "capabilities": [], + "active": True, + } + }, + "audit_events": [], + } + + +def ensure_person_store(data: dict[str, Any]) -> tuple[dict[str, Any], bool]: + if not isinstance(data, dict): + raise ValueError("store_invalid") + changed = False + root = data.get("unified_person") + if not isinstance(root, dict): + data["unified_person"] = empty_person_store() + return data, True + defaults = empty_person_store() + for key, value in defaults.items(): + if key not in root or not isinstance(root.get(key), type(value)): + root[key] = value.copy() if isinstance(value, dict) else list(value) if isinstance(value, list) else value + changed = True + root["version"] = max(1, int(root.get("version") or 0)) + return data, changed + + +def _list_text(value: Any, limit: int = 120, count: int = 12) -> list[str]: + if not isinstance(value, (list, tuple)): + return [] + result: list[str] = [] + for item in value: + try: + text = _text(item, "list_item", limit) + except ValueError: + continue + if text not in result: + result.append(text) + if len(result) >= count: + break + return result + + +def build_person_projection(store: dict[str, Any], person_id: str) -> dict[str, Any] | None: + root = store.get("unified_person") if isinstance(store, dict) else None + profiles = root.get("profiles") if isinstance(root, dict) and isinstance(root.get("profiles"), dict) else {} + profile = profiles.get(str(person_id or "")) + if not isinstance(profile, dict): + return None + identity_key = profile.get("resolved_identity_key") + policy_id = str(profile.get("relation_policy_id") or "default_friend") + policies = root.get("relation_policies") if isinstance(root.get("relation_policies"), dict) else {} + policy = policies.get(policy_id) if isinstance(policies.get(policy_id), dict) else {} + projection = { + "contract_name": CONTRACT_NAME, + "contract_version": CONTRACT_VERSION, + "contract_fingerprint": CONTRACT_FINGERPRINT, + "projection_schema_version": PROJECTION_SCHEMA_VERSION, + "projection_revision": max(1, int(profile.get("projection_revision") or 1)), + "person_id": str(profile.get("person_id") or ""), + "resolved_identity_key": str(identity_key or ""), + "identity_assurance": str(profile.get("identity_assurance") or "unverified"), + "profile_status": str(profile.get("profile_status") or "active"), + "display_name": str(profile.get("display_name") or ""), + "aliases": _list_text(profile.get("aliases")), + "relation_policy_id": policy_id, + "relation_label": str(policy.get("label") or "friend"), + "owner_mode": str(profile.get("owner_mode") or "not_owner"), + "affinity_score": max(-1200, min(1200, int(profile.get("affinity_score") or 0))), + "affinity_band": affinity_band(profile.get("affinity_score") or 0), + "relationship_capabilities": [ + item for item in _list_text(policy.get("capabilities"), 60) if item in RELATIONSHIP_CAPABILITIES + ], + "group_overlay_ref": str(profile.get("group_overlay_ref") or ""), + "updated_at": str(profile.get("updated_at") or ""), + } + return projection if not validate_projection(projection) else None + + +def validate_projection(projection: Any) -> list[str]: + if not isinstance(projection, dict): + return ["projection_invalid"] + errors = [f"missing_{field}" for field in PROJECTION_FIELDS if field not in projection] + if errors: + return errors + if projection.get("contract_name") != CONTRACT_NAME: + errors.append("contract_name_mismatch") + if projection.get("contract_version") != CONTRACT_VERSION: + errors.append("contract_version_mismatch") + if projection.get("contract_fingerprint") != CONTRACT_FINGERPRINT: + errors.append("contract_fingerprint_mismatch") + if projection.get("projection_schema_version") != PROJECTION_SCHEMA_VERSION: + errors.append("projection_schema_version_mismatch") + for field in ("person_id", "resolved_identity_key", "display_name", "relation_policy_id", "relation_label", "updated_at"): + value = projection.get(field) + if not isinstance(value, str) or not value or "\x00" in value or len(value) > 240: + errors.append(f"{field}_invalid") + if not re.fullmatch(r"chat-origin-v1:[0-9a-f]{64}", str(projection.get("resolved_identity_key") or "")): + errors.append("resolved_identity_key_invalid") + if not re.fullmatch(r"person_[0-9a-f]{24}", str(projection.get("person_id") or "")): + errors.append("person_id_invalid") + if not isinstance(projection.get("projection_revision"), int) or projection["projection_revision"] < 1: + errors.append("projection_revision_invalid") + if projection.get("identity_assurance") not in IDENTITY_ASSURANCE_VALUES: + errors.append("identity_assurance_invalid") + if projection.get("profile_status") not in PROFILE_STATUS_VALUES: + errors.append("profile_status_invalid") + if projection.get("owner_mode") not in OWNER_MODE_VALUES: + errors.append("owner_mode_invalid") + if not isinstance(projection.get("aliases"), list) or any(not isinstance(item, str) for item in projection["aliases"]): + errors.append("aliases_invalid") + if not isinstance(projection.get("relationship_capabilities"), list) or not set(projection["relationship_capabilities"]).issubset(RELATIONSHIP_CAPABILITIES): + errors.append("relationship_capabilities_invalid") + score = projection.get("affinity_score") + if not isinstance(score, int) or not -1200 <= score <= 1200: + errors.append("affinity_score_invalid") + elif projection.get("affinity_band") != affinity_band(score): + errors.append("affinity_band_inconsistent") + if projection.get("group_overlay_ref") is not None and not isinstance(projection.get("group_overlay_ref"), str): + errors.append("group_overlay_ref_invalid") + return errors + + +def resolve_identity(store: dict[str, Any], identity: dict[str, Any]) -> dict[str, Any]: + try: + identity_key = build_identity_key(identity) + except ValueError: + return {"state": "invalid", "identity_key": "", "person_id": "", "errors": ["identity_invalid"]} + root = store.get("unified_person") if isinstance(store, dict) else None + links = root.get("identity_links") if isinstance(root, dict) and isinstance(root.get("identity_links"), dict) else {} + link = links.get(identity_key) + if not isinstance(link, dict): + return {"state": "pending", "identity_key": identity_key, "person_id": ""} + person_id = str(link.get("person_id") or "") + projection = build_person_projection(store, person_id) + if projection is None: + return {"state": "invalid", "identity_key": identity_key, "person_id": person_id, "errors": ["projection_invalid"]} + return {"state": "resolved", "identity_key": identity_key, "person_id": person_id, "projection": projection} + + +def _safe_context_value(value: Any, depth: int = 0) -> Any: + if depth > 2: + return None + if isinstance(value, bool) or value is None or isinstance(value, (int, float)): + return value + if isinstance(value, str): + return value[:240] + if isinstance(value, (list, tuple)): + return [_safe_context_value(item, depth + 1) for item in list(value)[:12]] + if isinstance(value, dict): + result: dict[str, Any] = {} + for key, item in list(value.items())[:24]: + name = str(key).strip().lower() + if not name or name in CONTEXT_FORBIDDEN_KEYS: + continue + safe = _safe_context_value(item, depth + 1) + if safe is not None: + result[name[:80]] = safe + return result + return None + + +def make_context_slot(slot: str, payload: dict[str, Any] | None, *, owner: str = "", revision: int = 1, state: str = "ready", warnings: list[str] | None = None) -> dict[str, Any]: + slot_name = str(slot or "") + actual_owner = owner or P3_SLOT_OWNERS.get(slot_name, "unknown") + return { + "slot": slot_name, + "owner": actual_owner, + "revision": max(1, int(revision or 1)), + "contract_name": P3_CONTRACT_NAME, + "contract_version": P3_CONTRACT_VERSION, + "contract_fingerprint": P3_CONTRACT_FINGERPRINT, + "state": state if state in P3_SLOT_STATES else "invalid", + "payload": _safe_context_value(payload or {}) or {}, + "warnings": [str(item)[:120] for item in (warnings or [])[:8]], + } + + +def validate_context_slot(slot: Any, expected_name: str = "") -> list[str]: + if not isinstance(slot, dict): + return ["slot_invalid"] + errors: list[str] = [] + name = str(slot.get("slot") or "") + if name not in P3_SLOT_NAMES or (expected_name and name != expected_name): + errors.append("slot_name_invalid") + if slot.get("owner") != P3_SLOT_OWNERS.get(name): + errors.append("slot_owner_mismatch") + if slot.get("contract_name") != P3_CONTRACT_NAME or slot.get("contract_version") != P3_CONTRACT_VERSION: + errors.append("slot_contract_mismatch") + if slot.get("contract_fingerprint") != P3_CONTRACT_FINGERPRINT: + errors.append("slot_fingerprint_mismatch") + if not isinstance(slot.get("revision"), int) or slot["revision"] < 1: + errors.append("slot_revision_invalid") + if slot.get("state") not in P3_SLOT_STATES: + errors.append("slot_state_invalid") + if not isinstance(slot.get("payload"), dict): + errors.append("slot_payload_invalid") + return errors + + +def build_context_projection(slots: dict[str, dict[str, Any]] | None = None, *, state: str = "ready", revision: int = 1, warnings: list[str] | None = None) -> dict[str, Any]: + incoming = slots if isinstance(slots, dict) else {} + return { + "contract_name": P3_CONTRACT_NAME, + "contract_version": P3_CONTRACT_VERSION, + "contract_fingerprint": P3_CONTRACT_FINGERPRINT, + "revision": max(1, int(revision or 1)), + "state": state if state in P3_SLOT_STATES else "invalid", + "slots": {name: incoming.get(name, make_context_slot(name, {}, state="pending")) for name in P3_SLOT_NAMES}, + "warnings": [str(item)[:120] for item in (warnings or [])[:8]], + } + + +def validate_context_projection(context: Any) -> list[str]: + if not isinstance(context, dict): + return ["context_invalid"] + errors: list[str] = [] + if context.get("contract_name") != P3_CONTRACT_NAME or context.get("contract_version") != P3_CONTRACT_VERSION: + errors.append("context_contract_mismatch") + if context.get("contract_fingerprint") != P3_CONTRACT_FINGERPRINT: + errors.append("context_fingerprint_mismatch") + slots = context.get("slots") + if not isinstance(slots, dict): + return errors + ["context_slots_invalid"] + for name in P3_SLOT_NAMES: + errors.extend(validate_context_slot(slots.get(name), name)) + return errors + + +def merge_context_slots(existing: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]: + result = dict(existing) if isinstance(existing, dict) else build_context_projection() + old_slots = result.get("slots") if isinstance(result.get("slots"), dict) else {} + new_slots = incoming.get("slots") if isinstance(incoming, dict) and isinstance(incoming.get("slots"), dict) else {} + merged = dict(old_slots) + for name in P3_SLOT_NAMES: + candidate = new_slots.get(name) + if not isinstance(candidate, dict) or validate_context_slot(candidate, name): + continue + previous = merged.get(name) + if not isinstance(previous, dict) or int(candidate.get("revision") or 0) >= int(previous.get("revision") or 0): + merged[name] = candidate + result["slots"] = merged + result["revision"] = max(int(result.get("revision") or 1), int(incoming.get("revision") or 1) if isinstance(incoming, dict) else 1) + return result + + +def _contract_shape() -> dict[str, Any]: + return { + "name": CONTRACT_NAME, + "version": CONTRACT_VERSION, + "projection_schema_version": PROJECTION_SCHEMA_VERSION, + "identity_fields": list(IDENTITY_FIELDS), + "projection_fields": list(PROJECTION_FIELDS), + "p3_name": P3_CONTRACT_NAME, + "p3_version": P3_CONTRACT_VERSION, + "p3_slots": list(P3_SLOT_NAMES), + "p3_owners": dict(P3_SLOT_OWNERS), + } + + +CONTRACT_FINGERPRINT = hashlib.sha256(_canonical(_contract_shape()).encode("utf-8")).hexdigest()[:16] +P3_CONTRACT_FINGERPRINT = hashlib.sha256( + _canonical({"name": P3_CONTRACT_NAME, "version": P3_CONTRACT_VERSION, "slots": list(P3_SLOT_NAMES), "owners": P3_SLOT_OWNERS}).encode("utf-8") +).hexdigest()[:16] + + +def contract_self_check() -> list[str]: + errors: list[str] = [] + if CONTRACT_FINGERPRINT != hashlib.sha256(_canonical(_contract_shape()).encode("utf-8")).hexdigest()[:16]: + errors.append("contract_fingerprint_stale") + if P3_CONTRACT_FINGERPRINT != hashlib.sha256( + _canonical({"name": P3_CONTRACT_NAME, "version": P3_CONTRACT_VERSION, "slots": list(P3_SLOT_NAMES), "owners": P3_SLOT_OWNERS}).encode("utf-8") + ).hexdigest()[:16]: + errors.append("p3_contract_fingerprint_stale") + if set(P3_SLOT_NAMES) != set(P3_SLOT_OWNERS): + errors.append("p3_slot_owner_mismatch") + return errors + + +__all__ = [name for name in globals() if name.isupper() or name in { + "affinity_band", "build_context_projection", "build_identity_key", "build_person_projection", + "canonical_identity", "contract_self_check", "empty_person_store", "ensure_person_store", + "make_context_slot", "merge_context_slots", "person_id_for_identity", "resolve_identity", + "validate_context_projection", "validate_context_slot", "validate_projection", +}] diff --git a/tests/test_c2_context_orchestration.py b/tests/test_c2_context_orchestration.py new file mode 100644 index 0000000..c7369c9 --- /dev/null +++ b/tests/test_c2_context_orchestration.py @@ -0,0 +1,77 @@ +from __future__ import annotations + +import importlib + + +def load(name: str): + return importlib.import_module(name) + + +context = load("context_orchestration") +contract = load("person_context_contract") +shadow = load("p4_shadow") + + +def test_four_slots_have_contract_owners_and_revision(): + result = context.build_context( + {"persona": {"tone": "warm"}, "runtime": {"channel": "private"}, + "person": {"person_id": "person_abc"}, "scene": {"scope": "private"}}, + revisions={"persona": 2, "runtime": 3, "person": 4, "scene": 5}, + ) + assert set(result["slots"]) == set(contract.P3_SLOT_NAMES) + assert context.validate_context(result) == [] + for name in contract.P3_SLOT_NAMES: + assert result["slots"][name]["owner"] == contract.P3_SLOT_OWNERS[name] + assert result["slots"]["scene"]["revision"] == 5 + + +def test_revision_replay_is_idempotent_and_older_update_does_not_replace(): + first = context.build_context({"persona": {"tone": "warm"}}, revisions={"persona": 2}) + replay = context.build_context({"persona": {"tone": "warm"}}, revisions={"persona": 2}, existing=first) + older = context.build_context({"persona": {"tone": "cold"}}, revisions={"persona": 1}, existing=replay) + assert replay == first + assert older["slots"]["persona"]["payload"] == {"tone": "warm"} + + +def test_missing_and_bridge_degraded_are_explicit(): + assert context.build_context()["state"] == "legacy_local" + degraded = context.build_context({"runtime": {}}, bridge_available=False) + assert degraded["state"] == "degraded" + assert all(slot["state"] == "degraded" for slot in degraded["slots"].values()) + + +def test_person_slot_rejects_group_domain_facts(): + result = context.build_context({"person": {"display_name": "A", "group_id": "g1"}}) + slot = result["slots"]["person"] + assert slot["state"] == "invalid" + assert "person_group_domain_mixed" in slot["warnings"] + assert slot["payload"] == {} + + +def test_contract_fingerprint_mismatch_is_rejected(): + result = context.build_context({"persona": {"tone": "warm"}}) + result["contract_fingerprint"] = "wrong" + assert "context_fingerprint_mismatch" in context.validate_context(result) + assert context.project_context(result)["state"] == "degraded" + + +def test_p4_shadow_has_required_metadata_and_no_raw_text(): + record = shadow.build_p4_shadow( + source_kind="companion", target_kind="person", authority="runtime", + reason_code="context_observed", safe_reference="person_abc", + event_id="evt_1", timestamp="2026-07-30T00:00:00+00:00", + ) + assert shadow.validate_p4_shadow(record) == [] + assert record["shadow_only"] is True + assert "raw_prompt" not in record and "content" not in record + + +def test_p4_forbidden_input_is_explicit_invalid_and_not_copied(): + record = shadow.build_p4_shadow( + source_kind="companion", target_kind="person", authority="runtime", + reason_code="context_observed", event_id="evt_2", + metadata={"raw_prompt": "secret full conversation"}, + ) + assert record["status"] == "invalid" + assert "secret full conversation" not in repr(record) + assert shadow.validate_p4_shadow(record) == [] diff --git a/tests/test_c2_dual_plugin_link.py b/tests/test_c2_dual_plugin_link.py new file mode 100644 index 0000000..8634ae9 --- /dev/null +++ b/tests/test_c2_dual_plugin_link.py @@ -0,0 +1,91 @@ +from __future__ import annotations + +import importlib +import sys +import types +from copy import deepcopy +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +PEIBAN_ROOT = ROOT.parents[1] +MEMORY_ROOT = PEIBAN_ROOT / "astrbot_plugin_memory_companion-main" + + +def _load_memory_package(): + package_name = "c2_dual_memory" + package = types.ModuleType(package_name) + package.__path__ = [str(MEMORY_ROOT)] + sys.modules[package_name] = package + core = types.ModuleType(f"{package_name}.core") + core.__path__ = [str(MEMORY_ROOT / "core")] + sys.modules[core.__name__] = core + return importlib.import_module(f"{package_name}.core.bridge") + + +from context_orchestration import build_context +from person_context_contract import build_identity_key, empty_person_store +from unified_person_registry import UnifiedPersonRegistry + + +IDENTITY = { + "companion_instance_id": "chat-companion", + "bot_account_id": "qq:bot-1", + "adapter_instance_id": "qq:adapter-1", + "subject_namespace": "qq:user", + "platform_subject_id": "user-42", +} + + +def test_companion_projection_is_consumed_by_memory_bridge_without_cross_domain_write(): + store = {"unified_person": empty_person_store()} + registry = UnifiedPersonRegistry(store) + created = registry.create_or_link( + IDENTITY, + profile={"display_name": "Alice", "affinity_score": 10}, + operation_id="c2-dual-create", + ) + assert created["state"] == "resolved" + person_id = created["person_id"] + identity_key = build_identity_key(IDENTITY) + projection = registry.read_projection(person_id) + p3 = build_context( + persona={"companion_instance_id": "chat-companion"}, + runtime={"platform": "qq", "scope": "private"}, + person={"person_id": person_id, "projection_revision": projection["projection_revision"]}, + scene={"scope": "private", "group_scope": ""}, + ) + p3["person_id"] = person_id + p3["scope"] = "private" + before = deepcopy(store) + + bridge_module = _load_memory_package() + bridge = bridge_module.MemoryCompanionBridge(types.SimpleNamespace()) + person_result = bridge.consume_person_projection( + projection, + expected_identity_key=identity_key, + expected_person_id=person_id, + ) + context_result = bridge.consume_context_projection( + p3, + expected_person_id=person_id, + expected_scope="private", + ) + + assert person_result["state"] == "resolved" + assert context_result["state"] == "ready" + assert "display_name" not in person_result["projection_ref"] + assert store == before + + +def test_group_overlay_stays_scoped_and_memory_rejects_wrong_scope(): + store = {"unified_person": empty_person_store()} + registry = UnifiedPersonRegistry(store) + created = registry.create_or_link(IDENTITY, operation_id="c2-group-create") + person_id = created["person_id"] + first = registry.upsert_group_overlay(person_id, "qq:group:one", {"tone": "warm"}, operation_id="g1") + second = registry.upsert_group_overlay(person_id, "qq:group:two", {"tone": "quiet"}, operation_id="g2") + assert first["ok"] and second["ok"] + assert registry.read_group_overlay(person_id, "qq:group:one")["overlay"]["tone"] == "warm" + assert registry.read_group_overlay(person_id, "qq:group:two")["overlay"]["tone"] == "quiet" + assert registry.read_group_overlay(person_id, "qq:group:missing") is None diff --git a/tests/test_c2_unified_person.py b/tests/test_c2_unified_person.py new file mode 100644 index 0000000..7fb85a2 --- /dev/null +++ b/tests/test_c2_unified_person.py @@ -0,0 +1,69 @@ +from __future__ import annotations + +from person_context_contract import build_identity_key, ensure_person_store +from unified_person_registry import UnifiedPersonRegistry + + +def identity(platform="qq", subject="u-1", companion="c-1", bot="b-1", adapter="a-1"): + return { + "companion_instance_id": companion, + "bot_account_id": bot, + "adapter_instance_id": adapter, + "subject_namespace": platform, + "platform_subject_id": subject, + } + + +def test_five_dimension_identity_and_stable_id(): + a, b = {}, {} + left, right = UnifiedPersonRegistry(a), UnifiedPersonRegistry(b) + one = left.create_or_link(identity(), {"display_name": "小雪"}, operation_id="create-1") + two = right.create_or_link(identity(), {"display_name": "小雪"}, operation_id="create-2") + assert one["person_id"] == two["person_id"] + assert left.resolve(identity())["state"] == "resolved" + assert left.resolve(identity("qq", "u-1", "c-1", "b-2", "a-1"))["state"] == "pending" + + +def test_duplicate_create_is_idempotent_and_projection_valid(): + store = {} + registry = UnifiedPersonRegistry(store) + first = registry.create_or_link(identity(), operation_id="create-1") + second = registry.create_or_link(identity(), {"display_name": "other"}, operation_id="create-2") + assert first["person_id"] == second["person_id"] + assert second["changed"] is False + projection = registry.read_projection(first["person_id"]) + assert projection and projection["person_id"] == first["person_id"] + + +def test_link_projection_and_pending_without_explicit_operation(): + store = {} + registry = UnifiedPersonRegistry(store) + assert registry.create_or_link(identity(), operation_id="create")["state"] == "resolved" + person_id = registry.resolve(identity())["person_id"] + result = registry.link_identity(person_id, identity("telegram", "t-1"), operation_id="link-1") + assert result["state"] == "resolved" + assert registry.resolve(identity("telegram", "t-1"))["person_id"] == person_id + assert registry.create_or_link(identity("qq", "new"))["state"] == "pending" + + +def test_group_overlay_isolated_and_safe(): + store = {} + registry = UnifiedPersonRegistry(store) + person_id = registry.create_or_link(identity(), operation_id="create")["person_id"] + first = registry.upsert_group_overlay(person_id, "qq:group-1", {"nickname": "甲", "raw_prompt": "secret", "chat_text": "private"}, operation_id="g1") + second = registry.upsert_group_overlay(person_id, "qq:group-2", {"nickname": "乙"}, operation_id="g2") + assert first["state"] == second["state"] == "resolved" + assert registry.read_group_overlay(person_id, "qq:group-1")["overlay"] == {"nickname": "甲"} + assert registry.read_group_overlay(person_id, "qq:group-2")["overlay"] == {"nickname": "乙"} + assert registry.read_group_overlay(person_id, "qq:group-3") is None + assert "chat_text" not in str(store) + assert "raw_prompt" not in str(store) + + +def test_invalid_identity_and_corrupt_projection_are_explicit(): + store = {} + registry = UnifiedPersonRegistry(store) + assert registry.resolve({})["state"] == "invalid" + ensure_person_store(store) + store["unified_person"]["identity_links"]["bad"] = {"person_id": "person_bad"} + assert registry.status()["state"] in {"pending", "invalid"} diff --git a/unified_person_registry.py b/unified_person_registry.py new file mode 100644 index 0000000..3599729 --- /dev/null +++ b/unified_person_registry.py @@ -0,0 +1,284 @@ +"""Companion-owned Unified Person registry for the chat-side plugin. + +This module is deliberately a small boundary around ``person_context_contract``: +the companion may create and link identities, while consumers only read the +contract projection. Group overlays are scoped records and never become +profile facts. +""" +from __future__ import annotations + +from copy import deepcopy +from datetime import datetime, timezone +import hashlib +import json +import threading +from typing import Any + +try: + from .person_context_contract import ( + build_identity_key, + build_person_projection, + ensure_person_store, + person_id_for_identity, + resolve_identity, + validate_projection, + ) +except ImportError: + from person_context_contract import ( + build_identity_key, + build_person_projection, + ensure_person_store, + person_id_for_identity, + resolve_identity, + validate_projection, + ) + + +_LOCK = threading.RLock() +_FORBIDDEN = { + "raw_prompt", "prompt", "private_object", "private_object_ref", "object", + "chat_text", "content", "messages", "transcript", "database", +} +_IDENTITY_FIELDS = ( + "companion_instance_id", "bot_account_id", "adapter_instance_id", + "subject_namespace", "platform_subject_id", +) + + +def _now() -> str: + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +def _safe(value: Any, depth: int = 0) -> Any: + """Copy only bounded JSON-like values and drop context-bearing fields.""" + if depth > 2 or value is None or isinstance(value, bool): + return value + if isinstance(value, (int, float)): + return value + if isinstance(value, str): + return value[:240] + if isinstance(value, (list, tuple)): + return [_safe(item, depth + 1) for item in list(value)[:16]] + if isinstance(value, dict): + result: dict[str, Any] = {} + for key, item in list(value.items())[:32]: + name = str(key).strip().lower() + if not name or name in _FORBIDDEN: + continue + safe = _safe(item, depth + 1) + if safe is not None: + result[name[:80]] = safe + return result + return None + + +def _text(value: Any, field: str, limit: int = 200) -> str: + if not isinstance(value, str): + raise ValueError(f"{field}_invalid") + value = value.strip() + if not value or "\x00" in value or len(value) > limit: + raise ValueError(f"{field}_invalid") + return value + + +def _operation_id(value: Any) -> str: + if value in (None, ""): + return "" + return _text(value, "operation_id", 120) + + +def _identity(identity: Any) -> dict[str, str]: + if not isinstance(identity, dict): + raise ValueError("identity_invalid") + # build_identity_key is the contract authority; this explicit check also + # prevents accidental partial identity records from being persisted. + normalized = {field: _text(identity.get(field), field) for field in _IDENTITY_FIELDS} + normalized["subject_namespace"] = normalized["subject_namespace"].lower() + build_identity_key(normalized) + return normalized + + +def _root(store: dict[str, Any]) -> dict[str, Any]: + ensure_person_store(store) + root = store["unified_person"] + if not isinstance(root.get("profiles"), dict): + root["profiles"] = {} + if not isinstance(root.get("identity_links"), dict): + root["identity_links"] = {} + if not isinstance(root.get("group_overlays"), dict): + root["group_overlays"] = {} + if not isinstance(root.get("audit_events"), list): + root["audit_events"] = [] + if not isinstance(root.get("operations"), dict): + root["operations"] = {} + return root + + +def _fingerprint(value: Any) -> str: + encoded = json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + return hashlib.sha256(encoded.encode("utf-8")).hexdigest() + + +class UnifiedPersonRegistry: + """The only chat-side writer for Unified Person identity state.""" + + def __init__(self, store: dict[str, Any]) -> None: + if not isinstance(store, dict): + raise ValueError("store_invalid") + self._store = store + + def status(self) -> dict[str, Any]: + with _LOCK: + try: + root = _root(self._store) + except (TypeError, ValueError): + return {"state": "invalid", "profiles": 0, "identity_links": 0, "group_overlays": 0} + profiles = root["profiles"] + links = root["identity_links"] + overlays = root["group_overlays"] + state = "resolved" if profiles and links else "pending" + if any(not isinstance(item, dict) for item in profiles.values()): + state = "invalid" + return { + "state": state, + "version": int(root.get("version") or 1), + "profiles": len(profiles), + "identity_links": len(links), + "group_overlays": len(overlays), + } + + def resolve(self, identity: dict[str, Any]) -> dict[str, Any]: + with _LOCK: + try: + result = resolve_identity(self._store, identity) + except (TypeError, ValueError): + return {"state": "invalid", "identity_key": "", "person_id": "", "errors": ["identity_invalid"]} + if result.get("state") not in {"pending", "invalid", "resolved", "degraded"}: + result["state"] = "invalid" + return deepcopy(result) + + def create_or_link( + self, identity: dict[str, Any], profile: dict[str, Any] | None = None, + operation_id: str = "", actor_id: str = "companion", **_: Any, + ) -> dict[str, Any]: + """Create a person for an explicit operation, or return the existing link.""" + try: + normalized = _identity(identity) + op = _operation_id(operation_id) + actor = _text(actor_id, "actor_id", 120) + except ValueError: + return {"ok": False, "state": "invalid", "code": "invalid_request", "person_id": ""} + if not op: + return {"ok": False, "state": "pending", "code": "explicit_operation_required", "person_id": "", "identity_key": build_identity_key(normalized)} + safe_profile = _safe(profile or {}) + if not isinstance(safe_profile, dict): + safe_profile = {} + key = build_identity_key(normalized) + person_id = person_id_for_identity(normalized) + with _LOCK: + root = _root(self._store) + existing = root["identity_links"].get(key) + if isinstance(existing, dict) and existing.get("person_id"): + existing_id = str(existing["person_id"]) + projection = build_person_projection(self._store, existing_id) + state = "resolved" if projection and not validate_projection(projection) else "invalid" + return {"ok": state == "resolved", "state": state, "code": "already_linked", "person_id": existing_id, "identity_key": key, "projection": projection, "changed": False} + now = _now() + stored = { + "person_id": person_id, + "resolved_identity_key": key, + "identity_keys": [key], + "identity_assurance": "observed", + "profile_status": "active", + # The contract requires a non-empty display name. Keep the + # fallback generic; never derive it from message content. + "display_name": str(safe_profile.get("display_name") or "unknown_person"), + "aliases": safe_profile.get("aliases") if isinstance(safe_profile.get("aliases"), list) else [], + "relation_policy_id": str(safe_profile.get("relation_policy_id") or "default_friend"), + "owner_mode": str(safe_profile.get("owner_mode") or "not_owner"), + "affinity_score": int(safe_profile.get("affinity_score") or 0), + "group_overlay_ref": "", + "projection_revision": 1, + "updated_at": now, + } + root["profiles"][person_id] = stored + root["identity_links"][key] = { + "identity_key": key, "identity": normalized, "person_id": person_id, + "identity_assurance": "observed", "status": "active", + "created_at": now, "updated_at": now, "last_operation_id": op, + } + root["audit_events"].append({"event_id": op, "action": "create_or_link", "actor_id": actor, "person_id": person_id, "at": now}) + projection = build_person_projection(self._store, person_id) + if projection is None or validate_projection(projection): + return {"ok": False, "state": "invalid", "code": "projection_invalid", "person_id": person_id} + return {"ok": True, "state": "resolved", "code": "created", "person_id": person_id, "identity_key": key, "projection": projection, "changed": True} + + def link_identity(self, person_id: str, identity: dict[str, Any], operation_id: str = "", actor_id: str = "companion", **_: Any) -> dict[str, Any]: + try: + person_id = _text(person_id, "person_id") + normalized = _identity(identity) + op = _operation_id(operation_id) + _text(actor_id, "actor_id", 120) + except ValueError: + return {"ok": False, "state": "invalid", "code": "invalid_request", "person_id": ""} + if not op: + return {"ok": False, "state": "pending", "code": "explicit_operation_required", "person_id": person_id} + key = build_identity_key(normalized) + with _LOCK: + root = _root(self._store) + profile = root["profiles"].get(person_id) + if not isinstance(profile, dict): + return {"ok": False, "state": "pending", "code": "person_not_found", "person_id": person_id} + prior = root["identity_links"].get(key) + if isinstance(prior, dict) and prior.get("person_id") != person_id: + return {"ok": False, "state": "invalid", "code": "identity_conflict", "person_id": person_id} + root["identity_links"][key] = {"identity_key": key, "identity": normalized, "person_id": person_id, "identity_assurance": "explicit_linked", "status": "active", "updated_at": _now(), "last_operation_id": op} + if key not in profile.setdefault("identity_keys", []): + profile["identity_keys"].append(key) + profile["identity_assurance"] = "explicit_linked" + profile["projection_revision"] = int(profile.get("projection_revision") or 1) + 1 + profile["updated_at"] = _now() + projection = build_person_projection(self._store, person_id) + return {"ok": bool(projection and not validate_projection(projection)), "state": "resolved" if projection and not validate_projection(projection) else "invalid", "code": "identity_linked", "person_id": person_id, "identity_key": key, "projection": projection, "changed": True} + + def read_projection(self, person_id: str) -> dict[str, Any] | None: + with _LOCK: + projection = build_person_projection(self._store, str(person_id or "")) + return deepcopy(projection) if projection and not validate_projection(projection) else None + + def upsert_group_overlay(self, person_id: str, group_scope: str, overlay: dict[str, Any], operation_id: str = "", actor_id: str = "companion", **_: Any) -> dict[str, Any]: + try: + person_id, group_scope, op = _text(person_id, "person_id"), _text(group_scope, "group_scope", 240), _operation_id(operation_id) + _text(actor_id, "actor_id", 120) + except ValueError: + return {"ok": False, "state": "invalid", "code": "invalid_request", "person_id": person_id if isinstance(person_id, str) else ""} + if not op: + return {"ok": False, "state": "pending", "code": "explicit_operation_required", "person_id": person_id, "group_scope": group_scope} + safe = _safe(overlay) + if not isinstance(safe, dict): + return {"ok": False, "state": "invalid", "code": "overlay_invalid", "person_id": person_id, "group_scope": group_scope} + with _LOCK: + root = _root(self._store) + if not isinstance(root["profiles"].get(person_id), dict): + return {"ok": False, "state": "pending", "code": "person_not_found", "person_id": person_id, "group_scope": group_scope} + key = f"{person_id}:{_fingerprint(group_scope)[:32]}" + previous = root["group_overlays"].get(key) + revision = int(previous.get("revision") or 0) + 1 if isinstance(previous, dict) else 1 + root["group_overlays"][key] = {"person_id": person_id, "group_scope": group_scope, "overlay": safe, "revision": revision, "updated_at": _now(), "operation_id": op} + return {"ok": True, "state": "resolved", "code": "group_overlay_upserted", "person_id": person_id, "group_scope": group_scope, "revision": revision, "changed": previous != root["group_overlays"][key]} + + def read_group_overlay(self, person_id: str, group_scope: str) -> dict[str, Any] | None: + try: + person_id, group_scope = _text(person_id, "person_id"), _text(group_scope, "group_scope", 240) + except ValueError: + return None + with _LOCK: + root = _root(self._store) + key = f"{person_id}:{_fingerprint(group_scope)[:32]}" + record = root["group_overlays"].get(key) + if not isinstance(record, dict) or record.get("person_id") != person_id or record.get("group_scope") != group_scope: + return None + return deepcopy(record) + + +__all__ = ["UnifiedPersonRegistry"]