From f7d5a7c0db2fdf45f55ff7c6a0d2cb0842499ae4 Mon Sep 17 00:00:00 2001 From: YokiiroBW Date: Thu, 30 Jul 2026 09:37:53 +0800 Subject: [PATCH] feat(p4): add replayable effect preparation ledger --- core_store.py | 1 + tests/test_p4_b_effect_registry.py | 125 +++++++++++++ unified_person_registry.py | 277 ++++++++++++++++++++++++++++- 3 files changed, 402 insertions(+), 1 deletion(-) create mode 100644 tests/test_p4_b_effect_registry.py diff --git a/core_store.py b/core_store.py index 21e527b..3868afa 100644 --- a/core_store.py +++ b/core_store.py @@ -632,6 +632,7 @@ class CoreStoreMixin: "merge_people", "split_merged_people", "record_p4_shadow_event", + "record_p4_effect_event", }: return {"ok": False, "code": "unsupported_lifecycle_operation"} result = operation(*args, **kwargs) diff --git a/tests/test_p4_b_effect_registry.py b/tests/test_p4_b_effect_registry.py new file mode 100644 index 0000000..11fd0f5 --- /dev/null +++ b/tests/test_p4_b_effect_registry.py @@ -0,0 +1,125 @@ +# -*- coding: utf-8 -*- +"""P4-B preparation ledger remains separate from P4-A and profiles.""" +from __future__ import annotations + +from copy import deepcopy +import importlib +from pathlib import Path +import sys +import types +import unittest + +from unified_person_contract import empty_unified_person_store +from unified_person_registry import UnifiedPersonRegistry + + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import _host_stub # noqa: E402 + +_host_stub.install() +PACKAGE = "_p4_b_effect_registry_companion" +if PACKAGE not in sys.modules: + package = types.ModuleType(PACKAGE) + package.__path__ = [str(Path(__file__).resolve().parents[1])] + sys.modules[PACKAGE] = package +core_store_module = importlib.import_module(f"{PACKAGE}.core_store") + + +def identity(subject_id: str) -> dict[str, str]: + return { + "companion_instance_id": "companion-a", + "bot_account_id": "bot-1", + "adapter_instance_id": "telegram-main", + "subject_namespace": "telegram.user", + "platform_subject_id": subject_id, + } + + +def normal_event(event_id: str) -> dict[str, str]: + return {"event_id": event_id, "occurred_at": "2026-07-30T00:00:00Z", "kind": "normal"} + + +class _CoreStoreHost(core_store_module.CoreStoreMixin): + def __init__(self, data: dict) -> None: + self.data = data + self.save_calls = 0 + + def _schedule_data_save(self) -> None: + self.save_calls += 1 + + +class P4BEffectRegistryTests(unittest.TestCase): + def setUp(self) -> None: + self.store = {"unified_person": empty_unified_person_store()} + self.registry = UnifiedPersonRegistry(self.store) + + def _observe(self, subject_id: str) -> str: + result = self.registry.upsert_observed_identity(identity(subject_id), operation_id=f"observe-{subject_id}") + self.assertTrue(result["ok"]) + return result["person_id"] + + def _record(self, person_id: str, event_id: str, operation_id: str) -> dict: + return self.registry.record_p4_effect_event(person_id, normal_event(event_id), operation_id=operation_id, actor_id="p4-b-test") + + def test_effect_ledger_is_additive_and_never_creates_shadow_or_profile_effect(self) -> None: + person_id = self._observe("one") + before_profile = deepcopy(self.store["unified_person"]["profiles"][person_id]) + result = self._record(person_id, "p4-effect-1", "effect-operation-1") + self.assertTrue(result["ok"]) + self.assertEqual("p4_effect_event_recorded", result["code"]) + self.assertNotIn("p4_shadow", self.store["unified_person"]) + self.assertEqual(before_profile, self.store["unified_person"]["profiles"][person_id]) + entry = self.store["unified_person"]["p4_effect"]["people"][person_id] + self.assertEqual("effect_preparation", entry["state"]["mode"]) + self.assertEqual(person_id, entry["events"][0]["origin_person_id"]) + + def test_effect_event_and_operation_idempotence_are_fail_closed(self) -> None: + person_id = self._observe("two") + first = self._record(person_id, "p4-effect-idempotent", "effect-operation-idempotent") + self.assertTrue(first["ok"]) + snapshot = deepcopy(self.store) + repeated = self._record(person_id, "p4-effect-idempotent", "effect-operation-idempotent") + self.assertTrue(repeated["ok"]) + self.assertTrue(repeated["idempotent"]) + self.assertEqual(snapshot, self.store) + duplicate = self._record(person_id, "p4-effect-idempotent", "effect-operation-duplicate") + self.assertTrue(duplicate["ok"]) + self.assertTrue(duplicate["event_duplicate"]) + conflict = self.registry.record_p4_effect_event(person_id, {**normal_event("p4-effect-idempotent"), "occurred_at": "2026-07-31T00:00:00Z"}, operation_id="effect-operation-conflict", actor_id="p4-b-test") + self.assertEqual("p4_effect_event_id_conflict", conflict["code"]) + + def test_merge_replays_origins_and_split_restores_exact_pre_merge_effect_ledgers(self) -> None: + source, target = self._observe("three-source"), self._observe("three-target") + self.assertTrue(self._record(source, "p4-effect-source", "effect-source")["ok"]) + self.assertTrue(self._record(target, "p4-effect-target", "effect-target")["ok"]) + merged = self.registry.merge_people(source, target, operation_id="merge-effect", actor_id="operator", reason="test", authorized=True) + self.assertTrue(merged["ok"]) + merged_read = self.registry.read_p4_effect_state(target) + self.assertTrue(merged_read["ok"]) + self.assertEqual(2, merged_read["event_count"]) + origins = {item["origin_person_id"] for item in self.store["unified_person"]["p4_effect"]["people"][target]["events"]} + self.assertEqual({source, target}, origins) + split = self.registry.split_merged_people("merge-effect", operation_id="split-effect", actor_id="operator", reason="test", authorized=True) + self.assertTrue(split["ok"]) + self.assertEqual(1, self.registry.read_p4_effect_state(source)["event_count"]) + self.assertEqual(1, self.registry.read_p4_effect_state(target)["event_count"]) + + def test_split_rejects_effect_record_added_after_merge(self) -> None: + source, target = self._observe("four-source"), self._observe("four-target") + self.assertTrue(self._record(source, "p4-effect-source-2", "effect-source-2")["ok"]) + self.assertTrue(self.registry.merge_people(source, target, operation_id="merge-effect-2", actor_id="operator", reason="test", authorized=True)["ok"]) + self.assertTrue(self._record(target, "p4-effect-after-merge", "effect-after-merge")["ok"]) + split = self.registry.split_merged_people("merge-effect-2", operation_id="split-effect-2", actor_id="operator", reason="test", authorized=True) + self.assertEqual("p4_effect_split_conflict", split["code"]) + + def test_core_store_allows_only_the_write_operation(self) -> None: + person_id = self._observe("five") + host = _CoreStoreHost(self.store) + result = host._apply_unified_person_lifecycle("record_p4_effect_event", person_id, normal_event("p4-effect-core"), operation_id="effect-core", actor_id="p4-b-test") + self.assertTrue(result["ok"]) + self.assertEqual(1, host.save_calls) + self.assertEqual("unsupported_lifecycle_operation", host._apply_unified_person_lifecycle("read_p4_effect_state", person_id)["code"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/unified_person_registry.py b/unified_person_registry.py index 6bcc5a7..7dc5557 100644 --- a/unified_person_registry.py +++ b/unified_person_registry.py @@ -44,6 +44,7 @@ REGISTRY_VERSION = 1 _REGISTRY_LOCK = threading.RLock() _MAX_AUDIT_EVENTS = 1000 _P4_SHADOW_VERSION = 1 +_P4_EFFECT_VERSION = 1 def _now() -> str: @@ -256,6 +257,161 @@ def _p4_shadow_summary(state: dict[str, Any]) -> dict[str, Any]: } +def _p4_effect_container(root: dict[str, Any]) -> dict[str, Any]: + """Return the P4-B preparation ledger, never the P4-A shadow ledger.""" + container = root.get("p4_effect") + if not isinstance(container, dict): + container = {} + root["p4_effect"] = container + if not isinstance(container.get("version"), int): + container["version"] = _P4_EFFECT_VERSION + if not isinstance(container.get("people"), dict): + container["people"] = {} + return container + + +def _p4_effect_fingerprint(origin_person_id: str, event: dict[str, Any]) -> str: + return hashlib.sha256(_canonical({"origin_person_id": origin_person_id, "event": event}).encode("utf-8")).hexdigest() + + +def _p4_effect_state(events: list[dict[str, Any]]) -> dict[str, Any] | None: + replay = replay_shadow_events(events) + state = replay.get("state") if isinstance(replay, dict) else None + if not isinstance(state, dict): + return None + state = deepcopy(state) + state["mode"] = "effect_preparation" + return state + + +def _new_p4_effect_person_entry(person_id: str, now: str) -> dict[str, Any]: + state = new_shadow_state() + state["mode"] = "effect_preparation" + return { + "person_id": person_id, + "state": state, + "events": [], + "created_at": now, + "updated_at": now, + "last_operation_id": "", + } + + +def _replay_p4_effect_entry(entry: Any, person_id: str) -> tuple[dict[str, Any] | None, dict[str, dict[str, Any]] | None, str]: + """Validate an effect-preparation entry; origin survives a person merge.""" + if not isinstance(entry, dict) or entry.get("person_id") != person_id: + return None, None, "p4_effect_person_conflict" + envelopes = entry.get("events") + if not isinstance(envelopes, list): + return None, None, "p4_effect_corrupt" + event_index: dict[str, dict[str, Any]] = {} + events: list[dict[str, Any]] = [] + for envelope in envelopes: + if not isinstance(envelope, dict) or envelope.get("person_id") != person_id: + return None, None, "p4_effect_corrupt" + origin = envelope.get("origin_person_id") + event = envelope.get("event") + event_id = envelope.get("event_id") + if not isinstance(origin, str) or not origin or not isinstance(event, dict) or not isinstance(event_id, str): + return None, None, "p4_effect_corrupt" + if event.get("event_id") != event_id or event_id in event_index: + return None, None, "p4_effect_corrupt" + if envelope.get("event_fingerprint") != _p4_effect_fingerprint(origin, event): + return None, None, "p4_effect_corrupt" + event_index[event_id] = envelope + events.append(event) + state = _p4_effect_state(events) + if not isinstance(state, dict) or entry.get("state") != state: + return None, None, "p4_effect_state_mismatch" + return state, event_index, "" + + +def _p4_effect_summary(state: dict[str, Any]) -> dict[str, Any]: + return _p4_shadow_summary(state) + + +def _merge_p4_effect_people(root: dict[str, Any], source_person_id: str, target_person_id: str, operation_id: str, now: str) -> dict[str, Any] | None: + """Merge preparation records without changing P4-A or profile fields.""" + container = root.get("p4_effect") + if not isinstance(container, dict) or not isinstance(container.get("people"), dict): + return None + people = container["people"] + source_before = deepcopy(people.get(source_person_id)) + target_before = deepcopy(people.get(target_person_id)) + for entry, person_id in ((source_before, source_person_id), (target_before, target_person_id)): + if entry is not None: + _state, _index, error = _replay_p4_effect_entry(entry, person_id) + if error: + raise ValueError(error) + envelopes: list[dict[str, Any]] = [] + seen: dict[str, str] = {} + for entry in (target_before, source_before): + if not isinstance(entry, dict): + continue + for envelope in entry.get("events", []): + event_id = str(envelope.get("event_id") or "") if isinstance(envelope, dict) else "" + fingerprint = str(envelope.get("event_fingerprint") or "") if isinstance(envelope, dict) else "" + if not event_id or not fingerprint: + raise ValueError("p4_effect_corrupt") + previous = seen.get(event_id) + if previous is not None: + if previous != fingerprint: + raise ValueError("p4_effect_event_id_conflict") + continue + seen[event_id] = fingerprint + moved = deepcopy(envelope) + moved["person_id"] = target_person_id + envelopes.append(moved) + snapshot = {"source": source_before, "target": target_before} + if not envelopes: + return snapshot + state = _p4_effect_state([item["event"] for item in envelopes]) + if not isinstance(state, dict): + raise ValueError("p4_effect_replay_failed") + people[target_person_id] = { + "person_id": target_person_id, + "state": state, + "events": envelopes, + "created_at": str((target_before or source_before or {}).get("created_at") or now), + "updated_at": now, + "last_operation_id": operation_id, + } + people.pop(source_person_id, None) + return snapshot + + +def _restore_p4_effect_after_split(root: dict[str, Any], merge: dict[str, Any], source_person_id: str, target_person_id: str, merge_operation_id: str) -> str: + """Restore the exact pre-merge ledger or reject post-merge mutations.""" + if "p4_effect_snapshot" not in merge: + return "" + snapshot = merge.get("p4_effect_snapshot") + if not isinstance(snapshot, dict): + return "p4_effect_split_conflict" + container = root.get("p4_effect") + if not isinstance(container, dict) or not isinstance(container.get("people"), dict): + return "p4_effect_split_conflict" + people = container["people"] + current_source = people.get(source_person_id) + current_target = people.get(target_person_id) + if current_source is not None: + return "p4_effect_split_conflict" + if current_target is not None: + if not isinstance(current_target, dict) or current_target.get("last_operation_id") != merge_operation_id: + return "p4_effect_split_conflict" + _state, _index, error = _replay_p4_effect_entry(current_target, target_person_id) + if error: + return error + for person_id, key in ((source_person_id, "source"), (target_person_id, "target")): + previous = snapshot.get(key) + if previous is None: + people.pop(person_id, None) + elif isinstance(previous, dict): + people[person_id] = deepcopy(previous) + else: + return "p4_effect_split_conflict" + return "" + + class UnifiedPersonRegistry: """Companion-only lifecycle authority. No consumer receives a write method.""" @@ -494,6 +650,103 @@ class UnifiedPersonRegistry: self._commit(root) return result + def read_p4_effect_state(self, person_id: str) -> dict[str, Any]: + """Read P4-B preparation state without projecting it into a profile.""" + try: + person_id = _identifier(person_id, "person_id") + except ValueError: + return _result(False, "invalid_request") + with _REGISTRY_LOCK: + root = self._root_copy() + profile = root["profiles"].get(person_id) + if not isinstance(profile, dict): + return _result(False, "person_not_found", person_id=person_id) + if profile.get("profile_status") != "active": + return _result(False, "person_not_active", person_id=person_id) + entry = _p4_effect_container(root)["people"].get(person_id) + if entry is None: + state = _new_p4_effect_person_entry(person_id, "")["state"] + return _result(True, "p4_effect_empty", person_id=person_id, p4_effect_exists=False, p4_effect_state=state, p4_effect_summary=_p4_effect_summary(state), event_count=0) + state, event_index, error = _replay_p4_effect_entry(entry, person_id) + if error: + return _result(False, error, person_id=person_id) + assert state is not None and event_index is not None + return _result(True, "p4_effect_read", person_id=person_id, p4_effect_exists=True, p4_effect_state=state, p4_effect_summary=_p4_effect_summary(state), event_count=len(event_index)) + + def record_p4_effect_event( + self, + person_id: str, + event: dict[str, Any], + *, + operation_id: str, + actor_id: str = "system", + ) -> dict[str, Any]: + """Append one P4-B preparation event without a runtime effect. + + This is deliberately separate from ``record_p4_shadow_event``. It + writes no profile/projection field and is not connected to a Hook, + reply, confinement gate, or owner command. + """ + try: + operation_id = _identifier(operation_id, "operation_id", 120) + person_id = _identifier(person_id, "person_id") + actor_id = _identifier(actor_id, "actor_id", 160) + except ValueError: + return _result(False, "invalid_request") + if not isinstance(event, dict): + return _result(False, "invalid_p4_effect_event", operation_id=operation_id, person_id=person_id) + for field in ("person_id", "origin_person_id"): + if event.get(field) not in (None, "", person_id): + return _result(False, "p4_effect_person_mismatch", operation_id=operation_id, person_id=person_id) + normalized_event, event_errors = _normalize_p4_shadow_event(event) + if normalized_event is None: + return _result(False, "invalid_p4_effect_event", operation_id=operation_id, person_id=person_id, event_errors=event_errors) + event_id = str(normalized_event["event_id"]) + payload = {"person_id": person_id, "actor_id": actor_id, "event": normalized_event} + with _REGISTRY_LOCK: + root = self._root_copy() + repeated, fresh = _operation_result(root, operation_id, "record_p4_effect_event", payload) + if repeated is not None: + return repeated + profile = root["profiles"].get(person_id) + if not isinstance(profile, dict): + return _result(False, "person_not_found", operation_id=operation_id, person_id=person_id) + if profile.get("profile_status") != "active": + return _result(False, "person_not_active", operation_id=operation_id, person_id=person_id) + people = _p4_effect_container(root)["people"] + entry = people.get(person_id) + if entry is None: + entry = _new_p4_effect_person_entry(person_id, _now()) + event_index: dict[str, dict[str, Any]] = {} + else: + current_state, event_index, error = _replay_p4_effect_entry(entry, person_id) + if error: + return _result(False, error, operation_id=operation_id, person_id=person_id) + assert current_state is not None and event_index is not None + fingerprint = _p4_effect_fingerprint(person_id, normalized_event) + known = event_index.get(event_id) + if known is not None: + if known.get("event_fingerprint") != fingerprint: + return _result(False, "p4_effect_event_id_conflict", operation_id=operation_id, person_id=person_id, event_id=event_id) + result = _result(True, "p4_effect_event_duplicate", operation_id=operation_id, person_id=person_id, event_id=event_id, event_duplicate=True, p4_effect_summary=_p4_effect_summary(entry["state"])) + _record_operation(root, operation_id=operation_id, action="record_p4_effect_event", payload=payload, metadata={"event_id": event_id, "duplicate_event": True}, result=result, now=_now()) + self._commit(root) + return result + now = _now() + entry["events"].append({"event_id": event_id, "person_id": person_id, "origin_person_id": person_id, "event": deepcopy(normalized_event), "event_fingerprint": fingerprint, "recorded_at": now, "operation_id": operation_id}) + replay_state = _p4_effect_state([item["event"] for item in entry["events"]]) + if not isinstance(replay_state, dict): + return _result(False, "p4_effect_replay_failed", operation_id=operation_id, person_id=person_id) + entry["state"] = replay_state + entry["updated_at"] = now + entry["last_operation_id"] = operation_id + people[person_id] = entry + result = _result(True, "p4_effect_event_recorded", operation_id=operation_id, person_id=person_id, origin_person_id=person_id, event_id=event_id, changed=True, affected_person_ids=[person_id], audit_event_id=operation_id, p4_effect_summary=_p4_effect_summary(replay_state)) + _append_audit(root, operation_id=operation_id, action="p4_effect_event_recorded", actor_id=actor_id, code=result["code"], now=now, details={"person_id": person_id, "event_id": event_id, "event_kind": str(normalized_event.get("kind") or "invalid")}) + _record_operation(root, operation_id=operation_id, action="record_p4_effect_event", payload=payload, metadata={"event_id": event_id}, result=result, now=now) + self._commit(root) + return result + def upsert_observed_identity( self, identity: dict[str, Any], @@ -745,6 +998,16 @@ class UnifiedPersonRegistry: "overlays": before_overlays, "merged_aliases": merged_aliases, } + try: + p4_effect_snapshot = _merge_p4_effect_people( + root, + source_person_id, + target_person_id, + operation_id, + now, + ) + except ValueError as exc: + return _result(False, str(exc) or "p4_effect_merge_conflict", operation_id=operation_id) for key in moved_keys: link = links[key] link.update({"person_id": target_person_id, "previous_person_id": source_person_id, "merge_operation_id": operation_id, "updated_at": now, "last_operation_id": operation_id}) @@ -769,7 +1032,7 @@ class UnifiedPersonRegistry: overlay["person_id"] = target_person_id overlay["origin_person_id"] = source_person_id overlay["merge_operation_id"] = operation_id - root["merge_operations"][operation_id] = { + merge_record = { "operation_id": operation_id, "state": "active", "source_person_id": source_person_id, @@ -778,6 +1041,9 @@ class UnifiedPersonRegistry: "snapshot": snapshot, "created_at": now, } + if p4_effect_snapshot is not None: + merge_record["p4_effect_snapshot"] = p4_effect_snapshot + root["merge_operations"][operation_id] = merge_record result = _result(True, "people_merged", person_id=target_person_id, source_person_id=source_person_id, target_person_id=target_person_id, moved_identity_keys=moved_keys, changed=True, affected_person_ids=[source_person_id, target_person_id], projection_revision=target["projection_revision"], audit_event_id=operation_id) _append_audit(root, operation_id=operation_id, action="explicit_merge", actor_id=actor_id, code=result["code"], now=now, details={"source_person_id": source_person_id, "target_person_id": target_person_id, "reason": reason, "moved_identity_keys": moved_keys}) _record_operation(root, operation_id=operation_id, action="merge_people", payload=payload, metadata={}, result=result, now=now) @@ -841,6 +1107,15 @@ class UnifiedPersonRegistry: if not remaining_keys: return _result(False, "split_conflict", operation_id=operation_id) replacement_key = remaining_keys[0] + p4_effect_error = _restore_p4_effect_after_split( + root, + merge, + source_id, + target_id, + merge_operation_id, + ) + if p4_effect_error: + return _result(False, p4_effect_error, operation_id=operation_id) now = _now() source_revision = int(source.get("projection_revision") or 0) target_revision = int(target.get("projection_revision") or 0)