feat(p4): add replayable effect preparation ledger

这个提交存在于:
YokiiroBW 2026-07-30 09:37:53 +08:00
父节点 d7e8357898
当前提交 f7d5a7c0db
共有 3 个文件被更改,包括 402 次插入 和 1 次删除

查看文件

@ -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)

查看文件

@ -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()

查看文件

@ -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)