feat(p4): add host-bound manual review queue

这个提交存在于:
YokiiroBW 2026-07-30 16:54:48 +08:00
父节点 f02430a39a
当前提交 c6dd3e769a
共有 7 个文件被更改,包括 2213 次插入 和 3 次删除

查看文件

@ -9188,12 +9188,23 @@
"p4_b_safety_config": {
"description": "P4-B 实效前置隔离门",
"type": "object",
"hint": "默认关闭以保持旧版本兼容。开启后只隔离旧 relationship_score 直写,不启用 P4 实效、禁闭或 owner 命令。",
"hint": "默认关闭以保持旧版本兼容。人工审核仅记录独立队列和审计,不启用 P4 实效、禁闭、释放、恢复或 owner 命令。owner 白名单必须与 AstrBot event.get_sender_id() 运行时身份同时匹配。",
"items": {
"enable_p4_b_legacy_score_isolation": {
"description": "隔离旧关系分直写",
"type": "bool",
"default": false
},
"enable_p4_manual_review": {
"description": "启用 P4 人工审核候选观察与审计入口",
"type": "bool",
"default": false
},
"p4_manual_review_owner_ids": {
"description": "P4 人工审核 owner ID 白名单",
"type": "list",
"hint": "仅作 allowlist;运行时仍必须由 AstrBot event.get_sender_id() 返回相同单行 ID。兼容逗号或空白分隔字符串,不能用页面、请求、模型文本或事件字段自证授权。",
"default": []
}
}
},

查看文件

@ -623,6 +623,10 @@ class CoreStoreMixin:
return self._unified_person_registry().audit_events(limit=limit)
def _apply_unified_person_lifecycle(self, method: str, *args: Any, **kwargs: Any) -> dict[str, Any]:
if method in {"record_p4_manual_review_candidate", "record_p4_manual_review_decision"} and not bool(
getattr(self, "enable_p4_manual_review", False)
):
return {"ok": False, "code": "p4_review_disabled", "live_effect_permitted": False}
registry = self._unified_person_registry()
operation = getattr(registry, method, None)
if not callable(operation) or method not in {
@ -633,6 +637,8 @@ class CoreStoreMixin:
"split_merged_people",
"record_p4_shadow_event",
"record_p4_effect_event",
"record_p4_manual_review_candidate",
"record_p4_manual_review_decision",
}:
return {"ok": False, "code": "unsupported_lifecycle_operation"}
result = operation(*args, **kwargs)

217
main.py
查看文件

@ -18,7 +18,7 @@ import time
import unicodedata
import zoneinfo
from copy import deepcopy
from datetime import date, datetime, timedelta
from datetime import date, datetime, timedelta, timezone
from email.utils import parsedate_to_datetime
from http.cookies import SimpleCookie
from pathlib import Path
@ -142,6 +142,14 @@ from .p5_provenance_attestation import FIREWALL_STATUSES, P5AttestationRegistry
from .p5c_gate import RAW_IMAGE_PROVIDER_SINK, p5c_gate_allows
from .p5d_security_events import p5d_security_event_allows
from .p6_readonly_projection import build_p6_readonly_status
from .p4_manual_review import (
build_p3_review_proof,
_new_p4_review_attestation_registry,
P4ReviewAttestationRegistry,
parse_owner_allowlist,
runtime_owner_identity,
runtime_scope_identity,
)
from .segmented_message import flatten_component_chunks, split_plain_component_chain_detailed
from .token_budget import TokenBudgetMixin
from .balance_awareness import BalanceAwarenessMixin
@ -199,6 +207,9 @@ from .planning import (
)
P4_SHADOW_OBSERVER_PRIORITY = FINALIZE - 1000
# P4 manual review is a distinct, default-off observer after P3 finalization.
# Its queue is deliberately independent from both P4-A shadow and P4-B effect.
P4_MANUAL_REVIEW_OBSERVER_PRIORITY = P4_SHADOW_OBSERVER_PRIORITY - 1
# P5-A must publish source disposition before MemoryCompanion's P3 hook (-20),
# but after the companion context has assembled its known prompt sources.
P5_SOURCE_OBSERVER_PRIORITY = MEMORY_CONTEXT + 1
@ -1945,6 +1956,13 @@ class PrivateCompanionPlugin(
# legacy direct score writes while the separate effect ledger is
# prepared and remains default-off for rollback compatibility.
self.enable_p4_b_legacy_score_isolation = self._cfg_bool(c, "enable_p4_b_legacy_score_isolation", False)
# Manual P4 review is independently default-off. These configured
# IDs are an allowlist only; the review write path always obtains its
# actor from the actual AstrBot event.get_sender_id() runtime call.
self.enable_p4_manual_review = self._cfg_bool(c, "enable_p4_manual_review", False)
self.p4_manual_review_owner_ids = parse_owner_allowlist(
self._cfg_raw(c, "p4_manual_review_owner_ids", [])
)
# P5-A only observes source metadata. It never rewrites a prompt,
# changes a live tool set, or changes retrieval/response behaviour.
self.enable_p5_source_observer = self._cfg_bool(c, "enable_p5_source_observer", False)
@ -8322,7 +8340,10 @@ wakeup_type={_single_line(wakeup.get('type'), 40)} score={_single_line(wakeup.ge
def _safe_event_sender_id(event: AstrMessageEvent | None) -> str:
if event is None:
return ""
getter = getattr(event, "get_sender_id", None)
try:
getter = getattr(event, "get_sender_id", None)
except Exception:
return ""
if callable(getter):
try:
return _single_line(getter(), 80)
@ -9897,6 +9918,75 @@ wakeup_type={_single_line(wakeup.get('type'), 40)} score={_single_line(wakeup.ge
"""Expose the P5-D reject-only boundary without creating a live hook."""
return p5d_security_event_allows(self, operation, *opaque)
@staticmethod
def _p4_manual_review_runtime_sender_id(event: AstrMessageEvent | None) -> str:
"""Read a sender only from AstrBot's direct runtime API, never fields."""
if event is None:
return ""
try:
getter = getattr(event, "get_sender_id", None)
except Exception:
return ""
if not callable(getter):
return ""
try:
return _single_line(getter(), 160)
except Exception:
return ""
def _p4_manual_review_owner_runtime_identity(self, event: AstrMessageEvent | None) -> dict[str, Any]:
"""Expose the P4 owner double gate without treating config as a credential."""
return runtime_owner_identity(event, getattr(self, "p4_manual_review_owner_ids", ()))
def _p4_manual_review_attestation_registry(self) -> P4ReviewAttestationRegistry:
"""Return the host-owned, one-shot P3 observer attestation issuer."""
registry = getattr(self, "_p4_manual_review_registry", None)
if isinstance(registry, P4ReviewAttestationRegistry):
return registry
registry = _new_p4_review_attestation_registry()
setattr(self, "_p4_manual_review_registry", registry)
return registry
def submit_p4_manual_review_decision(
self,
event: AstrMessageEvent | None,
*,
person_id: str,
candidate_id: str,
operation_id: str,
decision: str,
reason_code: str,
) -> dict[str, Any]:
"""Write an audit-only manual P4 conclusion through the runtime gate.
This is an explicit host/API seam, not a model command, page action,
or automatic effect. The registry repeats the direct event identity
proof so a caller cannot bypass this method through a forged payload.
"""
if not bool(getattr(self, "enable_p4_manual_review", False)):
return {"ok": False, "code": "p4_review_disabled", "live_effect_permitted": False}
owner = self._p4_manual_review_owner_runtime_identity(event)
if owner.get("accepted") is not True:
return {
"ok": False,
"code": str(owner.get("code") or "p4_review_owner_runtime_unavailable"),
"live_effect_permitted": False,
}
try:
return self._apply_unified_person_lifecycle(
"record_p4_manual_review_decision",
event,
getattr(self, "p4_manual_review_owner_ids", ()),
person_id,
candidate_id,
operation_id=operation_id,
decision=decision,
reason_code=reason_code,
)
except Exception as exc:
logger.debug("[PrivateCompanion] P4 manual review decision rejected: %s", _single_line(exc, 160))
return {"ok": False, "code": "p4_review_runtime_error", "live_effect_permitted": False}
def _p4_b_apply_legacy_relationship_delta(
self,
user: Any,
@ -10390,6 +10480,129 @@ wakeup_type={_single_line(wakeup.get('type'), 40)} score={_single_line(wakeup.ge
_single_line(result.get("code") if isinstance(result, dict) else "", 120) or "unknown",
)
@staticmethod
def _p4_manual_review_expiry(created_at: str) -> str:
"""Return the fixed observer queue TTL, or an empty value on failure."""
if not isinstance(created_at, str) or not created_at:
return ""
try:
parsed = datetime.fromisoformat(
created_at[:-1] + "+00:00" if created_at.endswith("Z") else created_at
)
except (TypeError, ValueError):
return ""
if parsed.tzinfo is None:
return ""
return (parsed.astimezone(timezone.utc) + timedelta(hours=24)).isoformat(timespec="seconds").replace("+00:00", "Z")
@filter.on_llm_request(priority=P4_MANUAL_REVIEW_OBSERVER_PRIORITY)
async def observe_p4_manual_review_candidate(self, event: AstrMessageEvent, req: ProviderRequest, *args, **kwargs):
"""Queue a P3-finalized candidate only; never settle any P4 effect."""
if self is None or event is None or req is None:
return
if not bool(getattr(self, "enable_p4_manual_review", False)):
return
try:
state = read_context_state(request=req, event=event)
except Exception:
return
if not isinstance(state, dict) or state.get("phase") != "finalized" or state.get("finalized") is not True:
return
security = state.get("security")
if not isinstance(security, dict) or security.get("status") not in {"allowed", "sanitized"}:
return
if security.get("response_policy") == "deny":
return
created_at = state.get("created_at")
expires_at = self._p4_manual_review_expiry(created_at)
if not isinstance(created_at, str) or not expires_at:
return
# The target identity must also be rooted in the direct AstrBot getter;
# never fall back to event fields, P3 carrier values, or request data.
sender_id = self._p4_manual_review_runtime_sender_id(event)
if not sender_id:
return
scope = runtime_scope_identity(event)
scope_kind = str(scope.get("scope_kind") or "")
scope_id = str(scope.get("scope_id") or "")
if not scope_kind or not scope_id:
return
try:
message_id = self._event_message_id(event)
except Exception:
return
if not message_id:
return
try:
authority = self._memory_companion_unified_person_authority(
event,
expected_user_id=sender_id,
)
except Exception:
return
projection = authority.get("unified_person_projection") if isinstance(authority, dict) else None
source_identity = authority.get("unified_person_source_identity") if isinstance(authority, dict) else None
if not isinstance(projection, dict) or not isinstance(source_identity, dict):
return
person_id = _single_line(projection.get("person_id"), 160)
assurance = projection.get("identity_assurance")
if (
not person_id
or projection.get("profile_status") != "active"
or assurance not in {"verified", "explicit_linked"}
):
return
p3_proof = build_p3_review_proof(
state,
person_id=person_id,
identity_assurance=assurance,
scope_kind=scope_kind,
scope_id=scope_id,
)
if p3_proof is None:
return
digest = hashlib.sha256(message_id.encode("utf-8", errors="ignore")).hexdigest()
candidate = {
"candidate_id": f"p4.review.candidate:{digest}",
"event_id": f"p4.review.event:{digest}",
"person_id": person_id,
"created_at": created_at,
"expires_at": expires_at,
"reason_code": "p3_finalized_observed",
"scope_kind": scope_kind,
"scope_id": scope_id,
"p3_proof": p3_proof,
}
operation_id = f"p4.review.candidate:{person_id}:{digest}"
try:
producer_attestation = self._p4_manual_review_attestation_registry().mint(
req,
event,
state,
candidate,
operation_id=operation_id,
)
if producer_attestation is None:
return
result = self._apply_unified_person_lifecycle(
"record_p4_manual_review_candidate",
person_id,
candidate,
operation_id=operation_id,
producer_attestation=producer_attestation,
producer_request=req,
producer_event=event,
producer_state=state,
)
except Exception as exc:
logger.debug("[PrivateCompanion] P4 manual review candidate skipped: %s", _single_line(exc, 160))
return
if not isinstance(result, dict) or not result.get("ok"):
logger.debug(
"[PrivateCompanion] P4 manual review candidate rejected: code=%s",
_single_line(result.get("code") if isinstance(result, dict) else "", 120) or "unknown",
)
@filter.on_llm_response()
async def normalize_tts_enhancement_response(self, event: AstrMessageEvent, resp: LLMResponse, *args, **kwargs):
"""恢复降级为正文的生图调用,并规范化 TTS 标签。"""

864
p4_manual_review.py 普通文件
查看文件

@ -0,0 +1,864 @@
# -*- coding: utf-8 -*-
"""Default-off P4 manual-review contracts and isolated queue helpers.
This module intentionally knows nothing about P4 shadow settlement, P4 effect
preparation, model output, pages, request carriers, or live enforcement. A
review decision is only an audited queue record; it never causes a punishment,
release, recovery, reply, or memory write.
"""
from __future__ import annotations
from copy import deepcopy
from dataclasses import dataclass
from datetime import datetime, timezone
import hashlib
import json
import re
import threading
import time
import unicodedata
from typing import Any
try:
from .context_orchestration import (
CONTRACT_NAME as P3_CONTRACT_NAME,
CONTRACT_VERSION as P3_CONTRACT_VERSION,
LAYERS as P3_LAYERS,
contract_fingerprint as p3_contract_fingerprint,
)
except ImportError:
from context_orchestration import (
CONTRACT_NAME as P3_CONTRACT_NAME,
CONTRACT_VERSION as P3_CONTRACT_VERSION,
LAYERS as P3_LAYERS,
contract_fingerprint as p3_contract_fingerprint,
)
P4_REVIEW_VERSION = 1
P4_REVIEW_ALLOWED_SECURITY_STATUSES = frozenset({"allowed", "sanitized"})
P4_REVIEW_ALLOWED_ASSURANCES = frozenset({"verified", "explicit_linked"})
P4_REVIEW_ALLOWED_DECISIONS = frozenset({"approve", "reject"})
P4_REVIEW_ALLOWED_POLICIES = frozenset({"inherit", "allow"})
_MAX_ID_LENGTH = 160
_MAX_REASON_LENGTH = 120
_REASON_RE = re.compile(r"[a-z0-9][a-z0-9_.:-]{0,119}\Z")
_OWNER_PLACEHOLDERS = frozenset({"", "none", "null", "undefined", "default"})
_ATTESTATION_CREATION_TOKEN = object()
_HANDLE_CREATION_TOKEN = object()
P4_REVIEW_ATTESTATION_DEFAULT_TTL_SECONDS = 30.0
P4_REVIEW_ATTESTATION_MAX_ENTRIES = 1024
class P4ReviewProducerAttestationHandle:
"""Opaque, non-serializable, one-shot P3 observer attestation."""
__slots__ = ("_registry",)
def __init__(self, creation_token: object, registry: object) -> None:
if creation_token is not _HANDLE_CREATION_TOKEN:
raise TypeError("P4 review attestations are minted only by the host registry")
self._registry = registry
def __reduce__(self) -> object:
raise TypeError("P4 review attestations cannot be serialized")
def __reduce_ex__(self, protocol: int) -> object:
raise TypeError("P4 review attestations cannot be serialized")
def __getstate__(self) -> object:
raise TypeError("P4 review attestations cannot be serialized")
def __repr__(self) -> str:
return "<P4ReviewProducerAttestationHandle opaque>"
def __init_subclass__(cls, **kwargs: object) -> None:
raise TypeError("P4 review attestations cannot be subclassed")
@dataclass(slots=True)
class _ProducerAttestationEntry:
request: object
event: object
p3_state: object
candidate_fingerprint: str
candidate_id: str
event_id: str
person_id: str
scope_kind: str
scope_id: str
operation_id: str
expires_at: float
class P4ReviewAttestationRegistry:
"""Host-owned bounded issuer for exact-carrier, one-shot P4 review handles."""
def __init__(
self,
creation_token: object | None = None,
*,
clock: Any | None = None,
default_ttl_seconds: float = P4_REVIEW_ATTESTATION_DEFAULT_TTL_SECONDS,
max_entries: int = P4_REVIEW_ATTESTATION_MAX_ENTRIES,
) -> None:
if creation_token is not _ATTESTATION_CREATION_TOKEN:
raise TypeError("P4 review attestation registries are host-owned")
if isinstance(default_ttl_seconds, bool) or not isinstance(default_ttl_seconds, (int, float)):
raise TypeError("P4 review attestation TTL is invalid")
if default_ttl_seconds <= 0 or default_ttl_seconds > 300:
raise ValueError("P4 review attestation TTL is invalid")
if isinstance(max_entries, bool) or not isinstance(max_entries, int) or max_entries < 1:
raise ValueError("P4 review attestation capacity is invalid")
self._clock = clock or time.monotonic
self._default_ttl_seconds = float(default_ttl_seconds)
self._max_entries = max_entries
self._lock = threading.RLock()
self._entries: dict[P4ReviewProducerAttestationHandle, _ProducerAttestationEntry] = {}
self._unloaded = False
def mint(
self,
request: object,
event: object,
p3_state: object,
candidate: Any,
*,
operation_id: Any,
ttl_seconds: float | None = None,
) -> P4ReviewProducerAttestationHandle | None:
"""Mint only after binding all live carriers and the normalized candidate."""
if request is None or event is None or p3_state is None:
return None
try:
operation_id = _required_id(operation_id)
normalized, code = normalize_review_candidate(
candidate,
now=datetime.min.replace(tzinfo=timezone.utc),
)
except Exception:
return None
if not operation_id or normalized is None or code:
return None
try:
ttl = self._default_ttl_seconds if ttl_seconds is None else float(ttl_seconds)
except (TypeError, ValueError):
return None
if ttl <= 0 or ttl > 300:
return None
proof = build_p3_review_proof(
p3_state,
person_id=normalized["person_id"],
identity_assurance=normalized["p3_proof"]["identity_assurance"],
scope_kind=normalized["scope_kind"],
scope_id=normalized["scope_id"],
)
if proof is None or proof != normalized["p3_proof"]:
return None
with self._lock:
self._cleanup_locked(self._clock())
if self._unloaded or len(self._entries) >= self._max_entries:
return None
handle = P4ReviewProducerAttestationHandle(_HANDLE_CREATION_TOKEN, self)
self._entries[handle] = _ProducerAttestationEntry(
request=request,
event=event,
p3_state=p3_state,
candidate_fingerprint=candidate_fingerprint(normalized),
candidate_id=normalized["candidate_id"],
event_id=normalized["event_id"],
person_id=normalized["person_id"],
scope_kind=normalized["scope_kind"],
scope_id=normalized["scope_id"],
operation_id=operation_id,
expires_at=self._clock() + ttl,
)
return handle
def consume(
self,
handle: object,
request: object,
event: object,
p3_state: object,
candidate: Any,
*,
operation_id: Any,
) -> dict[str, str] | None:
"""Consume once; wrong carriers, candidate, operation or expiry fail closed."""
if type(handle) is not P4ReviewProducerAttestationHandle:
return None
try:
if handle._registry is not self:
return None
except Exception:
return None
with self._lock:
entry = self._entries.pop(handle, None)
if entry is None or self._unloaded or self._clock() >= entry.expires_at:
return None
if request is not entry.request or event is not entry.event or p3_state is not entry.p3_state:
return None
try:
operation_id = _required_id(operation_id)
normalized, code = normalize_review_candidate(
candidate,
now=datetime.min.replace(tzinfo=timezone.utc),
)
except Exception:
return None
if (
not operation_id
or operation_id != entry.operation_id
or normalized is None
or code
or normalized["candidate_id"] != entry.candidate_id
or normalized["event_id"] != entry.event_id
or normalized["person_id"] != entry.person_id
or normalized["scope_kind"] != entry.scope_kind
or normalized["scope_id"] != entry.scope_id
or candidate_fingerprint(normalized) != entry.candidate_fingerprint
):
return None
return {
"candidate_fingerprint": entry.candidate_fingerprint,
"candidate_id": entry.candidate_id,
"event_id": entry.event_id,
"person_id": entry.person_id,
"scope_kind": entry.scope_kind,
"scope_id": entry.scope_id,
"operation_id": entry.operation_id,
}
def pending_count(self) -> int:
with self._lock:
self._cleanup_locked(self._clock())
return len(self._entries)
def unload(self) -> None:
with self._lock:
self._entries.clear()
self._unloaded = True
def _cleanup_locked(self, now: float) -> None:
for handle, entry in list(self._entries.items()):
if now >= entry.expires_at:
self._entries.pop(handle, None)
def _new_p4_review_attestation_registry(
*,
clock: Any | None = None,
default_ttl_seconds: float = P4_REVIEW_ATTESTATION_DEFAULT_TTL_SECONDS,
max_entries: int = P4_REVIEW_ATTESTATION_MAX_ENTRIES,
) -> P4ReviewAttestationRegistry:
"""Create the host-owned issuer used by the P3 observer."""
return P4ReviewAttestationRegistry(
_ATTESTATION_CREATION_TOKEN,
clock=clock,
default_ttl_seconds=default_ttl_seconds,
max_entries=max_entries,
)
def consume_p4_review_producer_attestation(
handle: Any,
request: object,
event: object,
p3_state: object,
candidate: Any,
*,
operation_id: Any,
) -> dict[str, str] | None:
if type(handle) is not P4ReviewProducerAttestationHandle:
return None
try:
registry = handle._registry
except Exception:
return None
if not isinstance(registry, P4ReviewAttestationRegistry):
return None
return registry.consume(
handle,
request,
event,
p3_state,
candidate,
operation_id=operation_id,
)
def _canonical(value: Any) -> str:
return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
def _single_line_id(value: Any, *, limit: int = _MAX_ID_LENGTH) -> str:
"""Normalize one runtime/config ID without accepting a carrier-like value."""
if isinstance(value, bool) or not isinstance(value, (str, int)):
return ""
text = unicodedata.normalize("NFKC", str(value)).strip()
if not text or len(text) > limit or text.lower() in _OWNER_PLACEHOLDERS:
return ""
# IDs are deliberately one token: no newline, whitespace, NUL, or other
# control/format character may survive configuration parsing.
if any(character.isspace() or unicodedata.category(character).startswith("C") for character in text):
return ""
return text
def parse_owner_allowlist(value: Any) -> tuple[str, ...]:
"""Parse a config-only owner allowlist, accepting list/string separators.
The output is merely an allowlist. It is never a runtime credential: a
later gate must still obtain its actor from ``event.get_sender_id()``.
"""
raw_items: list[Any] = []
if isinstance(value, str):
raw_items.extend(piece for piece in re.split(r"[\s,,;;]+", value) if piece)
elif isinstance(value, (list, tuple, set, frozenset)):
for item in value:
if isinstance(item, str):
raw_items.extend(piece for piece in re.split(r"[\s,,;;]+", item) if piece)
else:
raw_items.append(item)
else:
raw_items.append(value)
result: list[str] = []
for raw in raw_items:
owner_id = _single_line_id(raw)
if owner_id and owner_id not in result:
result.append(owner_id)
return tuple(result)
def runtime_owner_identity(event: Any, configured_owner_ids: Any) -> dict[str, Any]:
"""Accept only a direct AstrBot runtime sender matching the config allowlist.
This intentionally does not inspect a dict, page field, request carrier,
model text, ``event.sender_id``, or ``event.user_id``. A test double is
valid only when it exposes a callable ``get_sender_id`` method.
"""
allowlist = parse_owner_allowlist(configured_owner_ids)
if not allowlist:
return {"accepted": False, "code": "p4_review_owner_allowlist_empty", "actor_id": ""}
if event is None:
return {"accepted": False, "code": "p4_review_owner_runtime_missing", "actor_id": ""}
try:
getter = getattr(event, "get_sender_id", None)
except Exception:
return {"accepted": False, "code": "p4_review_owner_runtime_unavailable", "actor_id": ""}
if not callable(getter):
return {"accepted": False, "code": "p4_review_owner_runtime_missing", "actor_id": ""}
try:
actor_id = _single_line_id(getter())
except Exception:
return {"accepted": False, "code": "p4_review_owner_runtime_unavailable", "actor_id": ""}
if not actor_id:
return {"accepted": False, "code": "p4_review_owner_runtime_invalid", "actor_id": ""}
if actor_id not in allowlist:
return {"accepted": False, "code": "p4_review_owner_not_allowed", "actor_id": ""}
return {
"accepted": True,
"code": "p4_review_owner_runtime_verified",
"actor_id": actor_id,
"allowlist_size": len(allowlist),
}
def runtime_scope_identity(event: Any) -> dict[str, str]:
"""Read a scope only from direct AstrBot runtime methods.
Group IDs must never fall back to raw payload fields or unified message
origins. Unknown or exceptional scope identity is therefore rejected.
"""
if event is None:
return {"scope_kind": "", "scope_id": ""}
try:
group_getter = getattr(event, "get_group_id", None)
except Exception:
return {"scope_kind": "", "scope_id": ""}
if not callable(group_getter):
return {"scope_kind": "", "scope_id": ""}
try:
group_id = _single_line_id(group_getter())
except Exception:
return {"scope_kind": "", "scope_id": ""}
if not group_id:
return {"scope_kind": "", "scope_id": ""}
try:
platform_getter = getattr(event, "get_platform_name", None)
except Exception:
return {"scope_kind": "", "scope_id": ""}
if not callable(platform_getter):
return {"scope_kind": "", "scope_id": ""}
try:
platform_id = _single_line_id(platform_getter())
except Exception:
return {"scope_kind": "", "scope_id": ""}
if not platform_id:
return {"scope_kind": "", "scope_id": ""}
return {"scope_kind": "group", "scope_id": f"{platform_id}:{group_id}"}
def _timestamp(value: Any) -> tuple[str, datetime | None]:
if not isinstance(value, str) or not value or len(value) > 80 or "\x00" in value:
return "", None
text = value.strip()
if not text or any(character.isspace() for character in text[:-1]):
return "", None
try:
parsed = datetime.fromisoformat(text[:-1] + "+00:00" if text.endswith("Z") else text)
except (TypeError, ValueError):
return "", None
if parsed.tzinfo is None:
return "", None
utc = parsed.astimezone(timezone.utc)
return utc.isoformat(timespec="seconds").replace("+00:00", "Z"), utc
def _reason_code(value: Any) -> str:
if not isinstance(value, str):
return ""
code = value.strip().lower()
return code if len(code) <= _MAX_REASON_LENGTH and _REASON_RE.fullmatch(code) else ""
def _required_id(value: Any) -> str:
return _single_line_id(value, limit=_MAX_ID_LENGTH)
def build_p3_review_proof(
state: Any,
*,
person_id: Any,
identity_assurance: Any,
scope_kind: Any,
scope_id: Any,
) -> dict[str, Any] | None:
"""Project only a validated P3 final state into the review contract."""
if not isinstance(state, dict):
return None
if (
state.get("contract_name") != P3_CONTRACT_NAME
or state.get("contract_version") != P3_CONTRACT_VERSION
or state.get("contract_fingerprint") != p3_contract_fingerprint()
or state.get("phase") != "finalized"
or state.get("finalized") is not True
or state.get("completed_layers") != list(P3_LAYERS)
):
return None
normalized_person_id = _required_id(person_id)
assurance = str(identity_assurance or "").strip()
normalized_scope_kind = str(scope_kind or "").strip().lower()
normalized_scope_id = _required_id(scope_id)
security = state.get("security")
if (
not normalized_person_id
or assurance not in P4_REVIEW_ALLOWED_ASSURANCES
or normalized_scope_kind != "group"
or not normalized_scope_id
or state.get("scope") != normalized_scope_kind
or not isinstance(security, dict)
or security.get("status") not in P4_REVIEW_ALLOWED_SECURITY_STATUSES
or security.get("response_policy") not in P4_REVIEW_ALLOWED_POLICIES
):
return None
security_event_id = security.get("event_id")
if not isinstance(security_event_id, str) or len(security_event_id) > 180 or "\x00" in security_event_id:
return None
created_at = state.get("created_at")
normalized_created_at, _ = _timestamp(created_at)
if not normalized_created_at:
return None
return {
"contract_name": P3_CONTRACT_NAME,
"contract_version": P3_CONTRACT_VERSION,
"contract_fingerprint": p3_contract_fingerprint(),
"completed_layers": list(P3_LAYERS),
"phase": "finalized",
"finalized": True,
"security_status": security["status"],
"response_policy": security["response_policy"],
"security_event_id": security_event_id,
"person_id": normalized_person_id,
"identity_assurance": assurance,
"scope_kind": normalized_scope_kind,
"scope_id": normalized_scope_id,
"created_at": normalized_created_at,
}
def normalize_review_candidate(candidate: Any, *, now: datetime | None = None) -> tuple[dict[str, Any] | None, str]:
"""Validate the immutable, observer-produced review-candidate contract."""
if not isinstance(candidate, dict):
return None, "p4_review_candidate_invalid"
candidate_id = _required_id(candidate.get("candidate_id"))
event_id = _required_id(candidate.get("event_id"))
person_id = _required_id(candidate.get("person_id"))
scope_kind = str(candidate.get("scope_kind") or "").strip().lower()
scope_id = _required_id(candidate.get("scope_id"))
reason_code = _reason_code(candidate.get("reason_code"))
created_at, created_when = _timestamp(candidate.get("created_at"))
expires_at, expires_when = _timestamp(candidate.get("expires_at"))
proof = candidate.get("p3_proof")
if not all((candidate_id, event_id, person_id, scope_kind, scope_id, reason_code, created_at, expires_at)):
return None, "p4_review_candidate_missing_required_field"
if scope_kind != "group":
return None, "p4_review_candidate_scope_invalid"
if created_when is None or expires_when is None or expires_when <= created_when:
return None, "p4_review_candidate_time_invalid"
if not isinstance(proof, dict):
return None, "p4_review_candidate_p3_proof_invalid"
proof_created_at, proof_when = _timestamp(proof.get("created_at"))
proof_fingerprint = proof.get("contract_fingerprint")
proof_layers = proof.get("completed_layers")
proof_policy = proof.get("response_policy")
proof_event_id = proof.get("security_event_id")
proof_scope_kind = str(proof.get("scope_kind") or "").strip().lower()
proof_scope_id = _required_id(proof.get("scope_id"))
if (
proof.get("contract_name") != P3_CONTRACT_NAME
or proof.get("contract_version") != P3_CONTRACT_VERSION
or proof_fingerprint != p3_contract_fingerprint()
or proof_layers != list(P3_LAYERS)
or proof.get("phase") != "finalized"
or proof.get("finalized") is not True
or proof.get("security_status") not in P4_REVIEW_ALLOWED_SECURITY_STATUSES
or proof_policy not in P4_REVIEW_ALLOWED_POLICIES
or not isinstance(proof_event_id, str)
or len(proof_event_id) > 180
or "\x00" in proof_event_id
or proof.get("person_id") != person_id
or proof.get("identity_assurance") not in P4_REVIEW_ALLOWED_ASSURANCES
or proof_scope_kind != scope_kind
or proof_scope_id != scope_id
or proof_created_at != created_at
or proof_when is None
):
return None, "p4_review_candidate_p3_proof_invalid"
clock = now or datetime.now(timezone.utc)
if expires_when <= clock.astimezone(timezone.utc):
return None, "p4_review_candidate_expired"
return {
"candidate_id": candidate_id,
"event_id": event_id,
"person_id": person_id,
"scope_kind": scope_kind,
"scope_id": scope_id,
"created_at": created_at,
"expires_at": expires_at,
"reason_code": reason_code,
"p3_proof": {
"phase": "finalized",
"finalized": True,
"contract_name": P3_CONTRACT_NAME,
"contract_version": P3_CONTRACT_VERSION,
"contract_fingerprint": p3_contract_fingerprint(),
"completed_layers": list(P3_LAYERS),
"security_status": proof["security_status"],
"response_policy": proof_policy,
"security_event_id": proof_event_id,
"person_id": person_id,
"identity_assurance": proof["identity_assurance"],
"scope_kind": scope_kind,
"scope_id": scope_id,
"created_at": created_at,
},
}, ""
def candidate_fingerprint(candidate: dict[str, Any]) -> str:
return hashlib.sha256(_canonical(candidate).encode("utf-8")).hexdigest()
def decision_fingerprint(record: dict[str, Any], *, candidate_fp: str) -> str:
return hashlib.sha256(
_canonical(
{
"candidate_fingerprint": candidate_fp,
"candidate_id": record.get("candidate_id"),
"event_id": record.get("event_id"),
"person_id": record.get("person_id"),
"scope_kind": record.get("scope_kind"),
"scope_id": record.get("scope_id"),
"actor_id": record.get("actor_id"),
"decision": record.get("decision"),
"reason_code": record.get("reason_code"),
"occurred_at": record.get("occurred_at"),
"operation_id": record.get("operation_id"),
}
).encode("utf-8")
).hexdigest()
def ensure_review_container(root: dict[str, Any]) -> tuple[dict[str, Any] | None, str]:
"""Create an additive ``unified_person.p4_review`` container once.
Existing malformed containers fail closed rather than being replaced.
"""
if not isinstance(root, dict):
return None, "p4_review_corrupt"
container = root.get("p4_review")
if container is None:
container = {
"version": P4_REVIEW_VERSION,
"candidates": {},
"event_index": {},
"decisions": {},
}
root["p4_review"] = container
return container, ""
if not isinstance(container, dict):
return None, "p4_review_corrupt"
if container.get("version") != P4_REVIEW_VERSION:
return None, "p4_review_corrupt"
for key in ("candidates", "event_index", "decisions"):
if not isinstance(container.get(key), dict):
return None, "p4_review_corrupt"
return container, ""
def queue_candidate(
container: dict[str, Any],
candidate: dict[str, Any],
*,
operation_id: str,
recorded_at: str,
) -> tuple[dict[str, Any] | None, str]:
"""Append a candidate to only the separate review queue."""
candidates = container.get("candidates")
event_index = container.get("event_index")
if not isinstance(candidates, dict) or not isinstance(event_index, dict):
return None, "p4_review_corrupt"
fingerprint = candidate_fingerprint(candidate)
candidate_id = candidate["candidate_id"]
event_id = candidate["event_id"]
known = candidates.get(candidate_id)
if known is not None:
if not isinstance(known, dict) or known.get("candidate_fingerprint") != fingerprint:
return None, "p4_review_candidate_id_conflict"
indexed_known = event_index.get(candidate["event_id"])
if (
not isinstance(indexed_known, dict)
or indexed_known.get("candidate_id") != candidate_id
or indexed_known.get("candidate_fingerprint") != fingerprint
):
return None, "p4_review_candidate_integrity_error"
return deepcopy(known), "p4_review_candidate_duplicate"
indexed = event_index.get(event_id)
if indexed is not None:
if not isinstance(indexed, dict) or indexed.get("candidate_fingerprint") != fingerprint:
return None, "p4_review_event_id_conflict"
return None, "p4_review_candidate_id_conflict"
record = {
**deepcopy(candidate),
"candidate_fingerprint": fingerprint,
"recorded_at": recorded_at,
"operation_id": operation_id,
}
candidates[candidate_id] = record
event_index[event_id] = {"candidate_id": candidate_id, "candidate_fingerprint": fingerprint}
return deepcopy(record), "p4_review_candidate_recorded"
def queue_decision(
container: dict[str, Any],
*,
person_id: str,
candidate_id: str,
actor_id: str,
scope_kind: str,
scope_id: str,
decision: str,
reason_code: str,
operation_id: str,
occurred_at: str,
now: datetime | None = None,
) -> tuple[dict[str, Any] | None, str]:
"""Append an audited conclusion without any live P4 effect."""
candidates = container.get("candidates")
event_index = container.get("event_index")
decisions = container.get("decisions")
if not isinstance(candidates, dict) or not isinstance(event_index, dict) or not isinstance(decisions, dict):
return None, "p4_review_corrupt"
candidate = candidates.get(candidate_id)
if not isinstance(candidate, dict):
return None, "p4_review_candidate_not_found"
normalized, code = normalize_review_candidate(candidate, now=now)
if normalized is None:
return None, code
stored_fingerprint = candidate.get("candidate_fingerprint")
if stored_fingerprint != candidate_fingerprint(normalized):
return None, "p4_review_candidate_integrity_error"
indexed = event_index.get(normalized["event_id"])
if (
not isinstance(indexed, dict)
or indexed.get("candidate_id") != candidate_id
or indexed.get("candidate_fingerprint") != stored_fingerprint
):
return None, "p4_review_candidate_integrity_error"
if normalized["person_id"] != person_id:
return None, "p4_review_candidate_person_mismatch"
if normalized["scope_kind"] != scope_kind or normalized["scope_id"] != scope_id:
return None, "p4_review_candidate_scope_mismatch"
existing = decisions.get(candidate_id)
if existing is not None:
if not isinstance(existing, dict):
return None, "p4_review_corrupt"
expected_existing = {
"candidate_id": candidate_id,
"event_id": normalized["event_id"],
"person_id": normalized["person_id"],
"scope_kind": normalized["scope_kind"],
"scope_id": normalized["scope_id"],
"actor_id": existing.get("actor_id"),
"decision": existing.get("decision"),
"reason_code": existing.get("reason_code"),
"occurred_at": existing.get("occurred_at"),
"operation_id": existing.get("operation_id"),
}
if (
existing.get("candidate_fingerprint") != stored_fingerprint
or existing.get("event_id") != expected_existing["event_id"]
or existing.get("person_id") != expected_existing["person_id"]
or existing.get("scope_kind") != expected_existing["scope_kind"]
or existing.get("scope_id") != expected_existing["scope_id"]
or existing.get("decision_fingerprint") != decision_fingerprint(expected_existing, candidate_fp=stored_fingerprint)
):
return None, "p4_review_decision_integrity_error"
if existing.get("decision") != decision:
return None, "p4_review_decision_conflict"
if (
existing.get("actor_id") != actor_id
or existing.get("reason_code") != reason_code
or existing.get("scope_kind") != scope_kind
or existing.get("scope_id") != scope_id
):
return None, "p4_review_decision_conflict"
return deepcopy(existing), "p4_review_decision_duplicate"
record = {
"candidate_id": candidate_id,
"event_id": normalized["event_id"],
"person_id": person_id,
"scope_kind": scope_kind,
"scope_id": scope_id,
"actor_id": actor_id,
"decision": decision,
"reason_code": reason_code,
"occurred_at": occurred_at,
"operation_id": operation_id,
}
record["candidate_fingerprint"] = stored_fingerprint
record["decision_fingerprint"] = decision_fingerprint(record, candidate_fp=stored_fingerprint)
decisions[candidate_id] = record
return deepcopy(record), "p4_review_decision_recorded"
def validate_review_operation_replay(
container: Any,
*,
action: str,
result: dict[str, Any],
payload: dict[str, Any],
) -> str:
"""Re-check the ledger envelope before returning a cached operation result."""
if not result.get("ok"):
return ""
if not isinstance(container, dict):
return "p4_review_corrupt"
candidates = container.get("candidates")
event_index = container.get("event_index")
decisions = container.get("decisions")
if not isinstance(candidates, dict) or not isinstance(event_index, dict) or not isinstance(decisions, dict):
return "p4_review_corrupt"
candidate_id = payload.get("candidate_id")
if not isinstance(candidate_id, str) and isinstance(payload.get("candidate"), dict):
candidate_id = payload["candidate"].get("candidate_id")
if not isinstance(candidate_id, str):
return "p4_review_candidate_integrity_error"
stored_candidate = candidates.get(candidate_id)
if not isinstance(stored_candidate, dict):
return "p4_review_candidate_integrity_error"
normalized_candidate, candidate_code = normalize_review_candidate(
stored_candidate,
now=datetime.min.replace(tzinfo=timezone.utc),
)
stored_candidate_fp = stored_candidate.get("candidate_fingerprint")
if (
normalized_candidate is None
or candidate_code
or stored_candidate_fp != candidate_fingerprint(normalized_candidate)
or normalized_candidate["person_id"] != payload.get("person_id")
or not isinstance(event_index.get(normalized_candidate["event_id"]), dict)
or event_index[normalized_candidate["event_id"]].get("candidate_id") != candidate_id
or event_index[normalized_candidate["event_id"]].get("candidate_fingerprint") != stored_candidate_fp
):
return "p4_review_candidate_integrity_error"
if (
result.get("candidate_id") is not None
and result.get("candidate_id") != candidate_id
) or (
result.get("person_id") is not None
and result.get("person_id") != normalized_candidate["person_id"]
):
return "p4_review_candidate_integrity_error"
if action == "record_p4_manual_review_candidate":
if result.get("event_id") is not None and result.get("event_id") != normalized_candidate["event_id"]:
return "p4_review_candidate_integrity_error"
return ""
if action != "record_p4_manual_review_decision":
return ""
stored_decision = decisions.get(candidate_id)
if not isinstance(stored_decision, dict):
return "p4_review_decision_integrity_error"
expected_decision = {
"candidate_id": candidate_id,
"event_id": normalized_candidate["event_id"],
"person_id": normalized_candidate["person_id"],
"scope_kind": normalized_candidate["scope_kind"],
"scope_id": normalized_candidate["scope_id"],
"actor_id": stored_decision.get("actor_id"),
"decision": stored_decision.get("decision"),
"reason_code": stored_decision.get("reason_code"),
"occurred_at": stored_decision.get("occurred_at"),
"operation_id": stored_decision.get("operation_id"),
}
if (
stored_decision.get("candidate_fingerprint") != stored_candidate_fp
or any(stored_decision.get(key) != value for key, value in expected_decision.items() if key not in {"candidate_id", "actor_id", "decision", "reason_code", "occurred_at", "operation_id"})
or stored_decision.get("decision_fingerprint") != decision_fingerprint(expected_decision, candidate_fp=stored_candidate_fp)
or stored_decision.get("actor_id") != payload.get("actor_id")
or stored_decision.get("decision") != payload.get("decision")
or stored_decision.get("reason_code") != payload.get("reason_code")
or stored_decision.get("scope_kind") != payload.get("scope_kind")
or stored_decision.get("scope_id") != payload.get("scope_id")
):
return "p4_review_decision_integrity_error"
return ""
def normalize_decision_request(
*,
person_id: Any,
candidate_id: Any,
decision: Any,
reason_code: Any,
operation_id: Any,
) -> tuple[dict[str, str] | None, str]:
normalized_person_id = _required_id(person_id)
normalized_candidate_id = _required_id(candidate_id)
normalized_operation_id = _required_id(operation_id)
normalized_reason_code = _reason_code(reason_code)
normalized_decision = decision.strip().lower() if isinstance(decision, str) else ""
if not all((normalized_person_id, normalized_candidate_id, normalized_operation_id, normalized_reason_code)):
return None, "p4_review_decision_invalid"
if normalized_decision not in P4_REVIEW_ALLOWED_DECISIONS:
return None, "p4_review_decision_invalid"
return {
"person_id": normalized_person_id,
"candidate_id": normalized_candidate_id,
"decision": normalized_decision,
"reason_code": normalized_reason_code,
"operation_id": normalized_operation_id,
}, ""

查看文件

@ -0,0 +1,586 @@
# -*- coding: utf-8 -*-
"""Pure P4 manual-review boundary tests: no P4 live effect is exercised."""
from __future__ import annotations
from copy import deepcopy
from datetime import datetime, timedelta, timezone
import importlib
from pathlib import Path
import sys
import types
import unittest
ROOT = Path(__file__).resolve().parents[1]
if str(ROOT) not in sys.path:
sys.path.insert(0, str(ROOT))
from p4_manual_review import (
P3_CONTRACT_NAME,
P3_CONTRACT_VERSION,
P3_LAYERS,
_new_p4_review_attestation_registry,
p3_contract_fingerprint,
parse_owner_allowlist,
runtime_owner_identity,
)
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_manual_review_core_store_companion"
if _PACKAGE not in sys.modules:
package = types.ModuleType(_PACKAGE)
package.__path__ = [str(ROOT)]
sys.modules[_PACKAGE] = package
core_store_module = importlib.import_module(f"{_PACKAGE}.core_store")
core_review_module = importlib.import_module(f"{_PACKAGE}.p4_manual_review")
context_module = importlib.import_module(f"{_PACKAGE}.context_orchestration")
def identity(subject_id: str) -> dict[str, str]:
return {
"companion_instance_id": "companion-a",
"bot_account_id": "bot-a",
"adapter_instance_id": "telegram-main",
"subject_namespace": "telegram.user",
"platform_subject_id": subject_id,
}
def timestamp(value: datetime) -> str:
return value.astimezone(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
def candidate(
person_id: str,
*,
token: str = "one",
assurance: str = "verified",
created_offset: timedelta = timedelta(),
expires_in: timedelta = timedelta(hours=1),
scope_id: str = "aiocqhttp:group-1",
) -> dict:
created = (datetime.now(timezone.utc) + created_offset).replace(microsecond=0)
created_at = timestamp(created)
return {
"candidate_id": f"candidate-{token}",
"event_id": f"event-{token}",
"person_id": person_id,
"scope_kind": "group",
"scope_id": scope_id,
"created_at": created_at,
"expires_at": timestamp(created + expires_in),
"reason_code": "p3_finalized_observed",
"p3_proof": {
"contract_name": P3_CONTRACT_NAME,
"contract_version": P3_CONTRACT_VERSION,
"contract_fingerprint": p3_contract_fingerprint(),
"completed_layers": list(P3_LAYERS),
"phase": "finalized",
"finalized": True,
"security_status": "allowed",
"response_policy": "inherit",
"security_event_id": "",
"person_id": person_id,
"identity_assurance": assurance,
"scope_kind": "group",
"scope_id": scope_id,
"created_at": created_at,
},
}
class _RuntimeEvent:
def __init__(self, sender_id: object = "owner-a", *, raises: bool = False, group_id: str = "group-1", platform: str = "aiocqhttp") -> None:
self._sender_id = sender_id
self._raises = raises
self._group_id = group_id
self._platform = platform
# These forged event fields must never be read by the owner gate.
self.sender_id = "forged-field-owner"
self.user_id = "forged-field-owner"
def get_group_id(self):
return self._group_id
def get_platform_name(self):
return self._platform
def get_sender_id(self):
if self._raises:
raise RuntimeError("runtime unavailable")
return self._sender_id
def _make_candidate_attestation(raw: dict, operation_id: str, review_module=None):
state = _build_p3_state(raw)
request = object()
event = _RuntimeEvent("sender-42")
registry = (review_module or sys.modules["p4_manual_review"])._new_p4_review_attestation_registry()
handle = registry.mint(request, event, state, raw, operation_id=operation_id)
return handle, request, event, state
def _build_p3_state(raw: dict) -> dict:
state = context_module.new_context_state(scope="group", created_at=raw["created_at"])
context_module.update_security(state, status=raw["p3_proof"]["security_status"], response_policy=raw["p3_proof"]["response_policy"])
for layer in context_module.LAYERS:
context_module.complete_layer(state, layer)
context_module.finalize_state(state)
return state
class _CoreStoreHost(core_store_module.CoreStoreMixin):
def __init__(self, data: dict) -> None:
self.data = data
self.save_calls = 0
self.enable_p4_manual_review = True
def _schedule_data_save(self) -> None:
self.save_calls += 1
class P4ManualReviewOwnerGateTests(unittest.TestCase):
def test_config_allowlist_parses_only_safe_single_line_ids(self) -> None:
self.assertEqual(
("owner-a", "owner-b", "owner-c", "123"),
parse_owner_allowlist([" owner-a, owner-b\nowner-c ", 123, "owner-a"]),
)
self.assertEqual((), parse_owner_allowlist({"owner": "not-a-list"}))
self.assertEqual((), parse_owner_allowlist(["owner-a\x00evil", "\n"]))
def test_runtime_owner_requires_direct_get_sender_id_and_allowlist_match(self) -> None:
accepted = runtime_owner_identity(_RuntimeEvent("owner-a"), "owner-a, owner-b")
self.assertTrue(accepted["accepted"])
self.assertEqual("owner-a", accepted["actor_id"])
cases = [
({"get_sender_id": lambda: "owner-a", "sender_id": "owner-a"}, "p4_review_owner_runtime_missing"),
(_RuntimeEvent("intruder"), "p4_review_owner_not_allowed"),
(_RuntimeEvent("owner-a\nforged"), "p4_review_owner_runtime_invalid"),
(_RuntimeEvent(raises=True), "p4_review_owner_runtime_unavailable"),
(None, "p4_review_owner_runtime_missing"),
]
for event, code in cases:
with self.subTest(code=code):
result = runtime_owner_identity(event, ["owner-a"])
self.assertFalse(result["accepted"])
self.assertEqual(code, result["code"])
class P4ManualReviewAttestationTests(unittest.TestCase):
def _mint(self, *, registry=None, operation_id="attestation-op"):
raw = candidate("person-attestation", token=operation_id)
state = _build_p3_state(raw)
request = object()
event = _RuntimeEvent("sender-42")
registry = registry or _new_p4_review_attestation_registry()
handle = registry.mint(request, event, state, raw, operation_id=operation_id)
self.assertIsNotNone(handle)
return registry, handle, request, event, state, raw
def test_attestation_binds_exact_carriers_candidate_and_operation_once(self) -> None:
registry, handle, request, event, state, raw = self._mint()
snapshot = registry.consume(handle, request, event, state, raw, operation_id="attestation-op")
self.assertIsInstance(snapshot, dict)
self.assertEqual("attestation-op", snapshot["operation_id"])
self.assertIsNone(registry.consume(handle, request, event, state, raw, operation_id="attestation-op"))
def test_wrong_carrier_or_candidate_consumes_handle_and_cannot_retry(self) -> None:
registry, handle, request, event, state, raw = self._mint()
wrong_candidate = deepcopy(raw)
wrong_candidate["reason_code"] = "different_reason"
self.assertIsNone(
registry.consume(handle, request, event, state, wrong_candidate, operation_id="attestation-op")
)
self.assertIsNone(registry.consume(handle, request, event, state, raw, operation_id="attestation-op"))
def test_fake_handle_and_expiry_fail_closed(self) -> None:
registry, handle, request, event, state, raw = self._mint()
self.assertIsNone(registry.consume(object(), request, event, state, raw, operation_id="attestation-op"))
now = [0.0]
expiring = _new_p4_review_attestation_registry(clock=lambda: now[0], default_ttl_seconds=1.0)
expiring_handle, expiring_request, expiring_event, expiring_state, expiring_raw = self._mint(
registry=expiring, operation_id="expiring-op"
)[1:]
now[0] = 2.0
self.assertIsNone(
expiring.consume(
expiring_handle,
expiring_request,
expiring_event,
expiring_state,
expiring_raw,
operation_id="expiring-op",
)
)
class P4ManualReviewRegistryTests(unittest.TestCase):
def setUp(self) -> None:
self.store = {"unified_person": empty_unified_person_store()}
self.registry = UnifiedPersonRegistry(self.store)
def _person(self, subject: str = "reviewer-target", *, assurance: str = "verified") -> str:
result = self.registry.upsert_observed_identity(identity(subject), operation_id=f"observe-{subject}")
self.assertTrue(result["ok"])
person_id = result["person_id"]
self.store["unified_person"]["profiles"][person_id]["identity_assurance"] = assurance
return person_id
def _queue(self, person_id: str, token: str = "one", *, operation_id: str | None = None, **kwargs) -> dict:
raw = candidate(person_id, token=token, **kwargs)
return self._record_candidate(person_id, raw, operation_id=operation_id or f"queue-{token}")
@staticmethod
def _p3_state(raw: dict) -> dict:
state = context_module.new_context_state(scope="group", created_at=raw["created_at"])
context_module.update_security(state, status=raw["p3_proof"]["security_status"], response_policy=raw["p3_proof"]["response_policy"])
for layer in context_module.LAYERS:
context_module.complete_layer(state, layer)
context_module.finalize_state(state)
return state
def _record_candidate(self, person_id: str, raw: dict, *, operation_id: str) -> dict:
attestation, request, event, state = self._mint(raw, operation_id=operation_id)
return self.registry.record_p4_manual_review_candidate(
person_id,
raw,
operation_id=operation_id,
producer_attestation=attestation,
producer_request=request,
producer_event=event,
producer_state=state,
)
def _mint(self, raw: dict, *, operation_id: str):
request = object()
event = _RuntimeEvent("sender-42")
state = self._p3_state(raw)
registry = _new_p4_review_attestation_registry()
attestation = registry.mint(request, event, state, raw, operation_id=operation_id)
return attestation, request, event, state
def test_candidate_queue_is_additive_and_ignores_forged_self_authorization(self) -> None:
person_id = self._person()
profile_before = deepcopy(self.store["unified_person"]["profiles"][person_id])
raw = candidate(person_id)
raw.update({"authorized": True, "approved": True, "owner": "forged-owner"})
result = self._record_candidate(person_id, raw, operation_id="queue-one")
self.assertTrue(result["ok"])
self.assertEqual("p4_review_candidate_recorded", result["code"])
self.assertFalse(result["live_effect_permitted"])
self.assertFalse(result["effect_applied"])
self.assertEqual(profile_before, self.store["unified_person"]["profiles"][person_id])
root = self.store["unified_person"]
self.assertIn("p4_review", root)
self.assertNotIn("p4_shadow", root)
self.assertNotIn("p4_effect", root)
saved = root["p4_review"]["candidates"]["candidate-one"]
self.assertNotIn("authorized", saved)
self.assertNotIn("approved", saved)
self.assertNotIn("owner", saved)
self.assertEqual("p4_manual_review_candidate_recorded", self.registry.audit_events()[-1]["action"])
def test_candidate_requires_observer_token_and_exact_p3_policy(self) -> None:
person_id = self._person("producer-boundary")
raw = candidate(person_id, token="producer-boundary")
denied = self.registry.record_p4_manual_review_candidate(
person_id, raw, operation_id="producer-missing"
)
self.assertEqual("p4_review_producer_unavailable", denied["code"])
original = candidate(person_id, token="producer-forged-policy")
attestation, request, event, state = self._mint(original, operation_id="producer-forged-policy")
forged = deepcopy(original)
forged["p3_proof"]["response_policy"] = "forged-policy"
invalid = self.registry.record_p4_manual_review_candidate(
person_id,
forged,
operation_id="producer-forged-policy",
producer_attestation=attestation,
producer_request=request,
producer_event=event,
producer_state=state,
)
self.assertEqual("p4_review_candidate_p3_proof_invalid", invalid["code"])
def test_missing_unknown_inactive_low_assurance_cross_person_and_expired_candidates_fail_closed(self) -> None:
missing = self.registry.record_p4_manual_review_candidate(
"person-missing", {"candidate_id": "only"}, operation_id="missing-fields"
)
self.assertEqual("p4_review_candidate_missing_required_field", missing["code"])
self.assertNotIn("p4_review", self.store["unified_person"])
person_id = self._person("unknown-check")
unknown = self._record_candidate("person-other", candidate("person-other", token="unknown"), operation_id="unknown")
self.assertEqual("person_not_found", unknown["code"])
cross_person = self._record_candidate(person_id, candidate("person-other", token="cross"), operation_id="cross")
self.assertEqual("p4_review_candidate_person_mismatch", cross_person["code"])
self.store["unified_person"]["profiles"][person_id]["profile_status"] = "suspended"
inactive = self._queue(person_id, "inactive")
self.assertEqual("person_not_active", inactive["code"])
self.store["unified_person"]["profiles"][person_id]["profile_status"] = "active"
self.store["unified_person"]["profiles"][person_id]["identity_assurance"] = "observed"
low_assurance = self._queue(person_id, "low")
self.assertEqual("p4_review_person_assurance_insufficient", low_assurance["code"])
self.store["unified_person"]["profiles"][person_id]["identity_assurance"] = "verified"
expired = self._queue(
person_id,
"expired",
created_offset=timedelta(hours=-2),
expires_in=timedelta(hours=1),
)
self.assertEqual("p4_review_candidate_expired", expired["code"])
self.assertNotIn("p4_review", self.store["unified_person"])
def test_candidate_idempotence_duplicate_and_conflicts_do_not_overwrite(self) -> None:
person_id = self._person("idempotence")
raw = candidate(person_id, token="idempotence")
first = self._record_candidate(person_id, raw, operation_id="candidate-op")
self.assertTrue(first["ok"])
snapshot = deepcopy(self.store)
repeated = self._record_candidate(person_id, deepcopy(raw), operation_id="candidate-op")
self.assertTrue(repeated["ok"])
self.assertTrue(repeated["idempotent"])
self.assertEqual(snapshot, self.store)
duplicate = self._record_candidate(person_id, deepcopy(raw), operation_id="candidate-duplicate-op")
self.assertTrue(duplicate["ok"])
self.assertTrue(duplicate["candidate_duplicate"])
self.assertFalse(duplicate["changed"])
conflict_snapshot = deepcopy(self.store)
conflicting_candidate = deepcopy(raw)
conflicting_candidate["reason_code"] = "different_reason"
conflict = self._record_candidate(person_id, conflicting_candidate, operation_id="candidate-conflict-op")
self.assertEqual("p4_review_candidate_id_conflict", conflict["code"])
self.assertEqual(conflict_snapshot, self.store)
operation_conflict = self._queue(person_id, "other", operation_id="candidate-op")
self.assertEqual("operation_id_conflict", operation_conflict["code"])
self.assertEqual(conflict_snapshot, self.store)
def test_decision_requires_runtime_owner_and_is_audit_only(self) -> None:
person_id = self._person("decision")
self.assertTrue(self._queue(person_id, "decision")["ok"])
profile_before = deepcopy(self.store["unified_person"]["profiles"][person_id])
forged = self.registry.record_p4_manual_review_decision(
{"sender_id": "owner-a", "authorized": True}, ["owner-a"], person_id, "candidate-decision",
operation_id="decision-forged", decision="approve", reason_code="manual_check",
)
self.assertEqual("p4_review_owner_runtime_missing", forged["code"])
approved = self.registry.record_p4_manual_review_decision(
_RuntimeEvent("owner-a"), ["owner-a"], person_id, "candidate-decision",
operation_id="decision-approve", decision="approve", reason_code="manual_check",
)
self.assertTrue(approved["ok"])
self.assertEqual("owner-a", approved["actor_id"])
self.assertFalse(approved["live_effect_permitted"])
self.assertEqual(profile_before, self.store["unified_person"]["profiles"][person_id])
root = self.store["unified_person"]
self.assertNotIn("p4_shadow", root)
self.assertNotIn("p4_effect", root)
decision = root["p4_review"]["decisions"]["candidate-decision"]
self.assertEqual("approve", decision["decision"])
self.assertEqual("owner-a", decision["actor_id"])
audit = self.registry.audit_events()[-1]
self.assertEqual("p4_manual_review_decision_recorded", audit["action"])
self.assertEqual("owner-a", audit["actor_id"])
def test_decision_idempotence_duplicate_and_opposite_decision_conflict(self) -> None:
person_id = self._person("decision-idempotence")
self.assertTrue(self._queue(person_id, "decision-idempotence")["ok"])
event = _RuntimeEvent("owner-a")
first = self.registry.record_p4_manual_review_decision(
event, "owner-a", person_id, "candidate-decision-idempotence",
operation_id="decision-op", decision="reject", reason_code="manual_reject",
)
self.assertTrue(first["ok"])
snapshot = deepcopy(self.store)
repeated = self.registry.record_p4_manual_review_decision(
event, "owner-a", person_id, "candidate-decision-idempotence",
operation_id="decision-op", decision="reject", reason_code="manual_reject",
)
self.assertTrue(repeated["idempotent"])
self.assertEqual(snapshot, self.store)
duplicate = self.registry.record_p4_manual_review_decision(
event, "owner-a", person_id, "candidate-decision-idempotence",
operation_id="decision-duplicate-op", decision="reject", reason_code="manual_reject",
)
self.assertTrue(duplicate["ok"])
self.assertTrue(duplicate["decision_duplicate"])
conflict_snapshot = deepcopy(self.store)
opposite = self.registry.record_p4_manual_review_decision(
event, "owner-a", person_id, "candidate-decision-idempotence",
operation_id="decision-opposite-op", decision="approve", reason_code="manual_approve",
)
self.assertEqual("p4_review_decision_conflict", opposite["code"])
self.assertEqual(conflict_snapshot, self.store)
operation_conflict = self.registry.record_p4_manual_review_decision(
event, "owner-a", person_id, "candidate-decision-idempotence",
operation_id="decision-op", decision="approve", reason_code="manual_approve",
)
self.assertEqual("operation_id_conflict", operation_conflict["code"])
self.assertEqual(conflict_snapshot, self.store)
other_group = _RuntimeEvent("owner-a", group_id="group-2")
cross_group = self.registry.record_p4_manual_review_decision(
other_group,
"owner-a",
person_id,
"candidate-decision-idempotence",
operation_id="decision-cross-group",
decision="reject",
reason_code="manual_reject",
)
self.assertEqual("p4_review_candidate_scope_mismatch", cross_group["code"])
same_operation_cross_group = self.registry.record_p4_manual_review_decision(
other_group,
"owner-a",
person_id,
"candidate-decision-idempotence",
operation_id="decision-op",
decision="reject",
reason_code="manual_reject",
)
self.assertEqual("operation_id_conflict", same_operation_cross_group["code"])
def test_candidate_and_decision_integrity_tampering_fails_closed(self) -> None:
person_id = self._person("integrity")
self.assertTrue(self._queue(person_id, "integrity")["ok"])
root = self.store["unified_person"]
root["p4_review"]["candidates"]["candidate-integrity"]["event_id"] = "event-tampered"
same_operation_candidate = self._record_candidate(
person_id,
candidate(person_id, token="integrity"),
operation_id="queue-integrity",
)
self.assertEqual("p4_review_candidate_integrity_error", same_operation_candidate["code"])
tampered_candidate = self.registry.record_p4_manual_review_decision(
_RuntimeEvent("owner-a"),
"owner-a",
person_id,
"candidate-integrity",
operation_id="integrity-decision",
decision="approve",
reason_code="manual_check",
)
self.assertEqual("p4_review_candidate_integrity_error", tampered_candidate["code"])
person_id = self._person("decision-integrity")
self.assertTrue(self._queue(person_id, "decision-integrity")["ok"])
approved = self.registry.record_p4_manual_review_decision(
_RuntimeEvent("owner-a"),
"owner-a",
person_id,
"candidate-decision-integrity",
operation_id="integrity-decision-ok",
decision="approve",
reason_code="manual_check",
)
self.assertTrue(approved["ok"])
root = self.store["unified_person"]
root["p4_review"]["decisions"]["candidate-decision-integrity"]["event_id"] = "event-tampered"
same_operation_decision = self.registry.record_p4_manual_review_decision(
_RuntimeEvent("owner-a"),
"owner-a",
person_id,
"candidate-decision-integrity",
operation_id="integrity-decision-ok",
decision="approve",
reason_code="manual_check",
)
self.assertEqual("p4_review_decision_integrity_error", same_operation_decision["code"])
tampered_decision = self.registry.record_p4_manual_review_decision(
_RuntimeEvent("owner-a"),
"owner-a",
person_id,
"candidate-decision-integrity",
operation_id="integrity-decision-replay",
decision="approve",
reason_code="manual_check",
)
self.assertEqual("p4_review_decision_integrity_error", tampered_decision["code"])
def test_core_store_allowlist_persists_only_new_review_queue_writes(self) -> None:
person_id = self._person("core-store")
host = _CoreStoreHost(self.store)
raw = candidate(person_id, token="core-store")
handle, request, event, state = _make_candidate_attestation(raw, "core-store-candidate", core_review_module)
queued = host._apply_unified_person_lifecycle(
"record_p4_manual_review_candidate",
person_id,
raw,
operation_id="core-store-candidate",
producer_attestation=handle,
producer_request=request,
producer_event=event,
producer_state=state,
)
self.assertTrue(queued["ok"])
self.assertEqual(1, host.save_calls)
repeated_raw = deepcopy(raw)
repeated_handle, repeated_request, repeated_event, repeated_state = _make_candidate_attestation(repeated_raw, "core-store-candidate", core_review_module)
repeated = host._apply_unified_person_lifecycle(
"record_p4_manual_review_candidate",
person_id,
repeated_raw,
operation_id="core-store-candidate",
producer_attestation=repeated_handle,
producer_request=repeated_request,
producer_event=repeated_event,
producer_state=repeated_state,
)
self.assertTrue(repeated["idempotent"])
self.assertEqual(1, host.save_calls)
decision = host._apply_unified_person_lifecycle(
"record_p4_manual_review_decision",
_RuntimeEvent("owner-a"),
["owner-a"],
person_id,
"candidate-core-store",
operation_id="core-store-decision",
decision="reject",
reason_code="manual_reject",
)
self.assertTrue(decision["ok"])
self.assertEqual(2, host.save_calls)
self.assertEqual(
"unsupported_lifecycle_operation",
host._apply_unified_person_lifecycle("read_p4_manual_review", person_id)["code"],
)
disabled_store = {"unified_person": empty_unified_person_store()}
disabled_host = _CoreStoreHost(disabled_store)
disabled_host.enable_p4_manual_review = False
disabled_person = UnifiedPersonRegistry(disabled_store).upsert_observed_identity(
identity("core-store-disabled"), operation_id="observe-core-store-disabled"
)["person_id"]
denied = disabled_host._apply_unified_person_lifecycle(
"record_p4_manual_review_candidate",
disabled_person,
candidate(disabled_person, token="disabled"),
operation_id="core-store-disabled",
)
self.assertEqual("p4_review_disabled", denied["code"])
self.assertEqual(0, disabled_host.save_calls)
if __name__ == "__main__":
unittest.main()

查看文件

@ -0,0 +1,195 @@
# -*- coding: utf-8 -*-
"""Observer/default-off tests for the P4 manual-review host seam."""
from __future__ import annotations
import asyncio
from copy import deepcopy
import hashlib
import importlib
from pathlib import Path
import sys
from types import SimpleNamespace
import types
import unittest
sys.path.insert(0, str(Path(__file__).resolve().parent))
import _host_stub # noqa: E402
_host_stub.install()
event_module = importlib.import_module("astrbot.api.event")
event_module.filter.EventMessageType = SimpleNamespace(
ALL="ALL", PRIVATE_MESSAGE="PRIVATE_MESSAGE", GROUP_MESSAGE="GROUP_MESSAGE"
)
PACKAGE = "_p4_manual_review_hook_companion"
if PACKAGE not in sys.modules:
package = types.ModuleType(PACKAGE)
package.__path__ = [str(Path(__file__).resolve().parents[1])]
sys.modules[PACKAGE] = package
contract = importlib.import_module(f"{PACKAGE}.context_orchestration")
main = importlib.import_module(f"{PACKAGE}.main")
PERSON_ID = "person_0123456789abcdef01234567"
def finalized_state(*, status: str = "allowed", response_policy: str = "inherit") -> dict:
state = contract.new_context_state(scope="group", created_at="2026-07-30T00:00:00.000Z")
contract.update_security(state, status=status, response_policy=response_policy)
for layer in contract.LAYERS:
contract.complete_layer(state, layer)
contract.finalize_state(state)
assert state["finalized"] is True
return state
class _Event:
def __init__(self, sender_id: str = "sender-42", message_id: str = "msg-42") -> None:
self._sender_id = sender_id
self.message_id = message_id
# Forged fields are intentionally different from the direct runtime ID.
self.sender_id = "forged-field"
self.user_id = "forged-field"
def get_group_id(self) -> str:
return "group-1"
def get_platform_name(self) -> str:
return "aiocqhttp"
def get_sender_id(self) -> str:
return self._sender_id
class _PoisonEvent(_Event):
def __getattribute__(self, name: str):
if name in {"get_sender_id", "get_group_id", "get_platform_name"}:
raise AssertionError(f"poisoned runtime getter: {name}")
return super().__getattribute__(name)
def get_sender_id(self) -> str:
return self._sender_id
class _Host:
def __init__(self, *, enabled: bool = False, assurance: str = "verified") -> None:
self.enable_p4_manual_review = enabled
self.assurance = assurance
self.calls: list[tuple[tuple, dict]] = []
self._p4_manual_review_registry = main._new_p4_review_attestation_registry()
_p4_manual_review_expiry = staticmethod(main.PrivateCompanionPlugin._p4_manual_review_expiry)
_p4_manual_review_runtime_sender_id = staticmethod(main.PrivateCompanionPlugin._p4_manual_review_runtime_sender_id)
def _p4_manual_review_attestation_registry(self):
return self._p4_manual_review_registry
@staticmethod
def _event_message_id(event: _Event) -> str:
return event.message_id
def _memory_companion_unified_person_authority(self, event: _Event, *, expected_user_id: str = "") -> dict:
if expected_user_id != "sender-42":
return {}
return {
"unified_person_projection": {
"person_id": PERSON_ID,
"profile_status": "active",
"identity_assurance": self.assurance,
},
"unified_person_source_identity": {"platform_subject_id": "sender-42"},
}
def _apply_unified_person_lifecycle(self, *args, **kwargs) -> dict:
self.calls.append((args, kwargs))
return {"ok": True, "code": "p4_review_candidate_recorded", "live_effect_permitted": False}
class P4ManualReviewHookTests(unittest.TestCase):
def _invoke(self, host: _Host, state: dict, *, event: _Event | None = None) -> None:
event = event or _Event()
request = SimpleNamespace(system_prompt="unchanged")
contract.attach_context_state(state, request, event)
before = deepcopy(state)
asyncio.run(main.PrivateCompanionPlugin.observe_p4_manual_review_candidate(host, event, request))
self.assertEqual("unchanged", request.system_prompt)
self.assertEqual(before, state)
def test_default_off_never_writes_a_candidate(self) -> None:
host = _Host(enabled=False)
self._invoke(host, finalized_state())
self.assertEqual([], host.calls)
def test_enabled_observer_requires_p3_and_persists_only_minimal_candidate(self) -> None:
self.assertEqual(main.P4_MANUAL_REVIEW_OBSERVER_PRIORITY, main.P4_SHADOW_OBSERVER_PRIORITY - 1)
host = _Host(enabled=True)
self._invoke(host, finalized_state())
self.assertEqual(1, len(host.calls))
args, kwargs = host.calls[0]
self.assertEqual(("record_p4_manual_review_candidate", PERSON_ID), args[:2])
candidate = args[2]
digest = hashlib.sha256(b"msg-42").hexdigest()
self.assertEqual(f"p4.review.candidate:{digest}", candidate["candidate_id"])
self.assertEqual(f"p4.review.event:{digest}", candidate["event_id"])
self.assertEqual(PERSON_ID, candidate["person_id"])
self.assertEqual("group", candidate["scope_kind"])
self.assertEqual("aiocqhttp:group-1", candidate["scope_id"])
self.assertEqual("p3_finalized_observed", candidate["reason_code"])
self.assertEqual("allowed", candidate["p3_proof"]["security_status"])
self.assertEqual("verified", candidate["p3_proof"]["identity_assurance"])
self.assertEqual("ops.context_orchestration.v1", candidate["p3_proof"]["contract_name"])
self.assertNotIn("msg-42", repr(candidate))
self.assertNotIn("forged-field", repr(candidate))
self.assertEqual(f"p4.review.candidate:{PERSON_ID}:{digest}", kwargs["operation_id"])
self.assertIn("producer_attestation", kwargs)
self.assertIn("producer_request", kwargs)
self.assertIn("producer_event", kwargs)
self.assertIn("producer_state", kwargs)
def test_observer_rejects_invalid_p3_sender_message_and_assurance_gates(self) -> None:
cases = [
(_Host(enabled=True), finalized_state(status="blocked"), _Event()),
(_Host(enabled=True), finalized_state(response_policy="deny"), _Event()),
(_Host(enabled=True, assurance="observed"), finalized_state(), _Event()),
(_Host(enabled=True), finalized_state(), _Event(sender_id="intruder")),
(_Host(enabled=True), finalized_state(), _Event(message_id="")),
]
for host, state, event in cases:
with self.subTest(event=event.message_id):
self._invoke(host, state, event=event)
self.assertEqual([], host.calls)
def test_poison_runtime_getters_fail_closed_without_escaping(self) -> None:
host = _Host(enabled=True)
self._invoke(host, finalized_state(), event=_PoisonEvent())
self.assertEqual([], host.calls)
def test_host_owner_gate_and_default_off_decision_seam_do_not_accept_fields(self) -> None:
host = SimpleNamespace(p4_manual_review_owner_ids=("owner-a",))
accepted = main.PrivateCompanionPlugin._p4_manual_review_owner_runtime_identity(
host, _Event(sender_id="owner-a")
)
self.assertTrue(accepted["accepted"])
denied = main.PrivateCompanionPlugin._p4_manual_review_owner_runtime_identity(
host, {"sender_id": "owner-a", "authorized": True}
)
self.assertFalse(denied["accepted"])
disabled = SimpleNamespace(enable_p4_manual_review=False)
result = main.PrivateCompanionPlugin.submit_p4_manual_review_decision(
disabled,
_Event(sender_id="owner-a"),
person_id=PERSON_ID,
candidate_id="candidate-any",
operation_id="decision-disabled",
decision="approve",
reason_code="manual_check",
)
self.assertEqual("p4_review_disabled", result["code"])
self.assertFalse(result["live_effect_permitted"])
if __name__ == "__main__":
unittest.main()

查看文件

@ -26,6 +26,18 @@ try:
replay_shadow_events,
settle_shadow_event,
)
from .p4_manual_review import (
P4_REVIEW_ALLOWED_ASSURANCES,
ensure_review_container,
normalize_decision_request,
normalize_review_candidate,
queue_candidate,
queue_decision,
validate_review_operation_replay,
runtime_owner_identity,
runtime_scope_identity,
consume_p4_review_producer_attestation,
)
except ImportError:
from unified_person_contract import (
build_identity_key,
@ -38,6 +50,18 @@ except ImportError:
replay_shadow_events,
settle_shadow_event,
)
from p4_manual_review import (
P4_REVIEW_ALLOWED_ASSURANCES,
ensure_review_container,
normalize_decision_request,
normalize_review_candidate,
queue_candidate,
queue_decision,
validate_review_operation_replay,
runtime_owner_identity,
runtime_scope_identity,
consume_p4_review_producer_attestation,
)
REGISTRY_VERSION = 1
@ -747,6 +771,317 @@ class UnifiedPersonRegistry:
self._commit(root)
return result
def record_p4_manual_review_candidate(
self,
person_id: str,
candidate: dict[str, Any],
*,
operation_id: str,
producer_attestation: Any = None,
producer_request: Any = None,
producer_event: Any = None,
producer_state: Any = None,
) -> dict[str, Any]:
"""Queue one P3-proven P4 review candidate in its own ledger only.
This is an observer write. It neither consults a claimed owner field
nor writes ``p4_shadow``/``p4_effect`` or a profile projection.
"""
try:
operation_id = _identifier(operation_id, "operation_id", 120)
person_id = _identifier(person_id, "person_id")
except ValueError:
return _result(False, "invalid_request")
# Validate all immutable fields before reading any prior operation, but
# postpone expiry to preserve an exact operation-ID replay result.
normalized, code = normalize_review_candidate(
candidate,
now=datetime.min.replace(tzinfo=timezone.utc),
)
if normalized is None:
return _result(False, code, operation_id=operation_id, person_id=person_id)
if normalized["person_id"] != person_id:
return _result(False, "p4_review_candidate_person_mismatch", operation_id=operation_id, person_id=person_id)
if producer_attestation is None:
return _result(False, "p4_review_producer_unavailable", operation_id=operation_id, person_id=person_id)
if (
consume_p4_review_producer_attestation(
producer_attestation,
producer_request,
producer_event,
producer_state,
candidate,
operation_id=operation_id,
)
is None
):
return _result(False, "p4_review_producer_attestation_invalid", operation_id=operation_id, person_id=person_id)
payload = {"person_id": person_id, "candidate": normalized}
with _REGISTRY_LOCK:
root = self._root_copy()
repeated, _fresh = _operation_result(root, operation_id, "record_p4_manual_review_candidate", payload)
if repeated is not None:
integrity_code = validate_review_operation_replay(
root.get("p4_review"),
action="record_p4_manual_review_candidate",
result=repeated,
payload=payload,
)
if integrity_code:
return _result(False, integrity_code, operation_id=operation_id, person_id=person_id)
return repeated
# Expiry is a live safety property only for new work. It does not
# weaken the replay guarantee for an already committed operation.
normalized, code = normalize_review_candidate(candidate, now=datetime.now(timezone.utc))
if normalized is None:
return _result(False, code, operation_id=operation_id, person_id=person_id)
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("person_id") != person_id:
return _result(False, "person_profile_conflict", 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)
assurance = profile.get("identity_assurance")
if assurance not in P4_REVIEW_ALLOWED_ASSURANCES:
return _result(False, "p4_review_person_assurance_insufficient", operation_id=operation_id, person_id=person_id)
if normalized["p3_proof"]["identity_assurance"] != assurance:
return _result(False, "p4_review_person_assurance_mismatch", operation_id=operation_id, person_id=person_id)
container, container_code = ensure_review_container(root)
if container is None:
return _result(False, container_code, operation_id=operation_id, person_id=person_id)
now = _now()
record, queue_code = queue_candidate(
container,
normalized,
operation_id=operation_id,
recorded_at=now,
)
if record is None:
return _result(False, queue_code, operation_id=operation_id, person_id=person_id)
candidate_id = normalized["candidate_id"]
if queue_code == "p4_review_candidate_duplicate":
result = _result(
True,
queue_code,
operation_id=operation_id,
person_id=person_id,
candidate_id=candidate_id,
event_id=normalized["event_id"],
candidate_duplicate=True,
live_effect_permitted=False,
effect_applied=False,
)
_record_operation(
root,
operation_id=operation_id,
action="record_p4_manual_review_candidate",
payload=payload,
metadata={"candidate_id": candidate_id, "duplicate_candidate": True},
result=result,
now=now,
)
self._commit(root)
return result
result = _result(
True,
queue_code,
operation_id=operation_id,
person_id=person_id,
candidate_id=candidate_id,
event_id=normalized["event_id"],
changed=True,
affected_person_ids=[person_id],
audit_event_id=operation_id,
live_effect_permitted=False,
effect_applied=False,
)
_append_audit(
root,
operation_id=operation_id,
action="p4_manual_review_candidate_recorded",
actor_id="p4_manual_review_observer",
code=result["code"],
now=now,
details={
"person_id": person_id,
"candidate_id": candidate_id,
"event_id": normalized["event_id"],
"reason_code": normalized["reason_code"],
"p3_security_status": normalized["p3_proof"]["security_status"],
},
)
_record_operation(
root,
operation_id=operation_id,
action="record_p4_manual_review_candidate",
payload=payload,
metadata={"candidate_id": candidate_id, "event_id": normalized["event_id"]},
result=result,
now=now,
)
self._commit(root)
return result
def record_p4_manual_review_decision(
self,
event: Any,
configured_owner_ids: Any,
person_id: str,
candidate_id: str,
*,
operation_id: str,
decision: str,
reason_code: str,
) -> dict[str, Any]:
"""Record a human conclusion only after direct runtime-owner proof.
``actor_id`` and ``occurred_at`` are deliberately not caller inputs:
the actor comes only from ``event.get_sender_id()`` and the timestamp
is produced by this persistence boundary. Approval remains audit-only.
"""
request, code = normalize_decision_request(
person_id=person_id,
candidate_id=candidate_id,
decision=decision,
reason_code=reason_code,
operation_id=operation_id,
)
if request is None:
return _result(False, code, operation_id=str(operation_id or ""), person_id=str(person_id or ""))
owner = runtime_owner_identity(event, configured_owner_ids)
if owner.get("accepted") is not True:
return _result(False, str(owner.get("code") or "p4_review_owner_runtime_unavailable"), operation_id=request["operation_id"], person_id=request["person_id"])
actor_id = str(owner["actor_id"])
scope = runtime_scope_identity(event)
scope_kind = str(scope.get("scope_kind") or "")
scope_id = str(scope.get("scope_id") or "")
if not scope_kind or not scope_id:
return _result(False, "p4_review_scope_runtime_unavailable", operation_id=request["operation_id"], person_id=request["person_id"])
payload = {
"person_id": request["person_id"],
"candidate_id": request["candidate_id"],
"actor_id": actor_id,
"scope_kind": scope_kind,
"scope_id": scope_id,
"decision": request["decision"],
"reason_code": request["reason_code"],
}
with _REGISTRY_LOCK:
root = self._root_copy()
repeated, _fresh = _operation_result(root, request["operation_id"], "record_p4_manual_review_decision", payload)
if repeated is not None:
integrity_code = validate_review_operation_replay(
root.get("p4_review"),
action="record_p4_manual_review_decision",
result=repeated,
payload=payload,
)
if integrity_code:
return _result(False, integrity_code, operation_id=request["operation_id"], person_id=request["person_id"])
return repeated
profile = root["profiles"].get(request["person_id"])
if not isinstance(profile, dict):
return _result(False, "person_not_found", operation_id=request["operation_id"], person_id=request["person_id"])
if profile.get("person_id") != request["person_id"]:
return _result(False, "person_profile_conflict", operation_id=request["operation_id"], person_id=request["person_id"])
if profile.get("profile_status") != "active":
return _result(False, "person_not_active", operation_id=request["operation_id"], person_id=request["person_id"])
if profile.get("identity_assurance") not in P4_REVIEW_ALLOWED_ASSURANCES:
return _result(False, "p4_review_person_assurance_insufficient", operation_id=request["operation_id"], person_id=request["person_id"])
container = root.get("p4_review")
if not isinstance(container, dict):
return _result(False, "p4_review_candidate_not_found", operation_id=request["operation_id"], person_id=request["person_id"])
if container.get("version") != 1 or any(not isinstance(container.get(key), dict) for key in ("candidates", "event_index", "decisions")):
return _result(False, "p4_review_corrupt", operation_id=request["operation_id"], person_id=request["person_id"])
now = _now()
record, queue_code = queue_decision(
container,
person_id=request["person_id"],
candidate_id=request["candidate_id"],
actor_id=actor_id,
scope_kind=scope_kind,
scope_id=scope_id,
decision=request["decision"],
reason_code=request["reason_code"],
operation_id=request["operation_id"],
occurred_at=now,
now=datetime.now(timezone.utc),
)
if record is None:
return _result(False, queue_code, operation_id=request["operation_id"], person_id=request["person_id"])
if queue_code == "p4_review_decision_duplicate":
result = _result(
True,
queue_code,
operation_id=request["operation_id"],
person_id=request["person_id"],
candidate_id=request["candidate_id"],
decision=request["decision"],
scope_kind=scope_kind,
scope_id=scope_id,
decision_duplicate=True,
live_effect_permitted=False,
effect_applied=False,
)
_record_operation(
root,
operation_id=request["operation_id"],
action="record_p4_manual_review_decision",
payload=payload,
metadata={"candidate_id": request["candidate_id"], "duplicate_decision": True},
result=result,
now=now,
)
self._commit(root)
return result
result = _result(
True,
queue_code,
operation_id=request["operation_id"],
person_id=request["person_id"],
candidate_id=request["candidate_id"],
event_id=record["event_id"],
decision=request["decision"],
actor_id=actor_id,
occurred_at=now,
scope_kind=scope_kind,
scope_id=scope_id,
changed=True,
affected_person_ids=[request["person_id"]],
audit_event_id=request["operation_id"],
live_effect_permitted=False,
effect_applied=False,
)
_append_audit(
root,
operation_id=request["operation_id"],
action="p4_manual_review_decision_recorded",
actor_id=actor_id,
code=result["code"],
now=now,
details={
"person_id": request["person_id"],
"candidate_id": request["candidate_id"],
"event_id": record["event_id"],
"decision": request["decision"],
"reason_code": request["reason_code"],
"scope_kind": scope_kind,
"scope_id": scope_id,
},
)
_record_operation(
root,
operation_id=request["operation_id"],
action="record_p4_manual_review_decision",
payload=payload,
metadata={"candidate_id": request["candidate_id"], "decision": request["decision"]},
result=result,
now=now,
)
self._commit(root)
return result
def upsert_observed_identity(
self,
identity: dict[str, Any],