# -*- coding: utf-8 -*- """P3 versioned, metadata-only request context contract.""" from __future__ import annotations import hashlib import json import re from copy import deepcopy from datetime import datetime, timezone from typing import Any CONTRACT_NAME = "ops.context_orchestration.v1" CONTRACT_VERSION = "1.0" ATTRIBUTE_NAME = "_ops_context_orchestration_v1" LAYERS = ("persona", "runtime", "person", "scene", "memory", "safety") PHASES = ("initialized", "companion_ready", "memory_ready", "safety_ready", "finalized", "invalid") SECURITY_STATUSES = ("allowed", "sanitized", "blocked", "quarantined", "unavailable") POLICIES = ("inherit", "allow", "deny", "quarantine") TRUST_LEVELS = ("T0", "T1", "T2", "T3", "T4") CONTEXT_INIT, COMPANION_CONTEXT, TTS_FALLBACK, MEMORY_CONTEXT = 100, 0, -10, -20 INCOMPATIBLE_TOOL, SENSITIVE_TOOL, FINALIZE = -20000, -21000, -22000 MAX_FRAGMENTS, MAX_ERRORS, MAX_REASON_CODES = 64, 16, 16 _FRAGMENT_FIELDS = ("key", "layer", "source", "trust_level", "content_hash", "chars", "status") _CORE = ("persona", "runtime", "person", "scene") _STATE_FIELDS = {"contract_name", "contract_version", "contract_fingerprint", "request_id", "session_id", "scope", "created_at", "phase", "completed_layers", "fragments", "security", "errors", "finalized"} _SECURITY_FIELDS = {"status", "event_id", "memory_policy", "tool_policy", "response_policy", "reason_codes"} _CODE_RE = re.compile(r"^[a-z0-9][a-z0-9_.:-]{0,119}$") def _json(value: Any) -> str: return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")) def contract_descriptor(*, fixture_version: str = "1") -> dict[str, Any]: return {"contract_name": CONTRACT_NAME, "contract_version": CONTRACT_VERSION, "attribute_name": ATTRIBUTE_NAME, "fixture_version": str(fixture_version), "layers": list(LAYERS), "phases": list(PHASES), "security_statuses": list(SECURITY_STATUSES), "policies": list(POLICIES), "trust_levels": list(TRUST_LEVELS), "state_fields": ["contract_name", "contract_version", "contract_fingerprint", "request_id", "session_id", "scope", "created_at", "phase", "completed_layers", "fragments", "security", "errors", "finalized"], "security_fields": ["status", "event_id", "memory_policy", "tool_policy", "response_policy", "reason_codes"], "fragment_fields": list(_FRAGMENT_FIELDS), "limits": {"fragments": MAX_FRAGMENTS, "errors": MAX_ERRORS, "reason_codes": MAX_REASON_CODES}} def contract_fingerprint(*, fixture_version: str = "1") -> str: return hashlib.sha256(_json(contract_descriptor(fixture_version=fixture_version)).encode("utf-8")).hexdigest() def _text(value: Any, limit: int = 240) -> str: return str(value or "").replace("\r", " ").replace("\n", " ").strip()[:limit] def _utc_timestamp(value: Any = None) -> str: if value is None: return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z") if not isinstance(value, str) or value != value.strip() or "T" not in value or not value.endswith("Z"): return "" try: datetime.fromisoformat(value[:-1] + "+00:00") except ValueError: return "" return value def _security() -> dict[str, Any]: return {"status": "allowed", "event_id": "", "memory_policy": "inherit", "tool_policy": "inherit", "response_policy": "inherit", "reason_codes": []} def new_context_state(*, request_id: Any = "", session_id: Any = "", scope: Any = "unknown", created_at: Any = None, fixture_version: str = "1") -> dict[str, Any]: return {"contract_name": CONTRACT_NAME, "contract_version": CONTRACT_VERSION, "contract_fingerprint": contract_fingerprint(fixture_version=fixture_version), "request_id": _text(request_id, 180), "session_id": _text(session_id), "scope": _text(scope, 80) or "unknown", "created_at": _utc_timestamp(created_at), "phase": "initialized", "completed_layers": [], "fragments": [], "security": _security(), "errors": [], "finalized": False} def _error(state: dict[str, Any], code: str) -> None: errors = state.setdefault("errors", []) if isinstance(errors, list) and code not in errors and len(errors) < MAX_ERRORS: errors.append(code) def _invalid(state: dict[str, Any], code: str) -> dict[str, Any]: _error(state, code); state["phase"] = "invalid"; state["finalized"] = False return state def consume_context_state(value: Any, *, fixture_version: str = "1") -> dict[str, Any] | None: if not isinstance(value, dict): return None state = value if state.get("contract_name") != CONTRACT_NAME or state.get("contract_version") != CONTRACT_VERSION: return _invalid(state, "contract_mismatch") if state.get("contract_fingerprint") != contract_fingerprint(fixture_version=fixture_version): return _invalid(state, "fingerprint_mismatch") if set(state) != _STATE_FIELDS or state.get("phase") not in PHASES or not isinstance(state.get("finalized"), bool): return _invalid(state, "state_invalid") if not isinstance(state.get("created_at"), str) or not state["created_at"] or _utc_timestamp(state["created_at"]) != state["created_at"]: return _invalid(state, "created_at_invalid") completed = state.get("completed_layers") if not isinstance(completed, list): return _invalid(state, "state_invalid") if any(layer not in LAYERS for layer in completed) or len(completed) != len(set(completed)) or completed != sorted(completed, key=LAYERS.index): return _invalid(state, "completed_layers_invalid") if state["finalized"] != (state["phase"] == "finalized"): return _invalid(state, "finalized_phase_invalid") if state["finalized"] and set(completed) != set(LAYERS): return _invalid(state, "finalized_layers_invalid") if not isinstance(state.get("fragments"), list) or len(state["fragments"]) > MAX_FRAGMENTS: return _invalid(state, "fragments_invalid") for fragment in state["fragments"]: if not isinstance(fragment, dict) or set(fragment) != set(_FRAGMENT_FIELDS) or fragment.get("layer") not in LAYERS or fragment.get("trust_level") not in TRUST_LEVELS: return _invalid(state, "fragment_invalid") security = state.get("security") if not isinstance(security, dict) or set(security) != _SECURITY_FIELDS or security.get("status") not in SECURITY_STATUSES or any(security.get(key) not in POLICIES for key in ("memory_policy", "tool_policy", "response_policy")): return _invalid(state, "security_invalid") errors = state.get("errors") reason_codes = security.get("reason_codes") if not isinstance(reason_codes, list) or len(reason_codes) > MAX_REASON_CODES or not isinstance(errors, list) or len(errors) > MAX_ERRORS: return _invalid(state, "limits_invalid") if any(not isinstance(code, str) or _CODE_RE.fullmatch(code) is None for code in [*errors, *reason_codes]): return _invalid(state, "codes_invalid") return state def attach_context_state(state: dict[str, Any], request: Any | None = None, event: Any | None = None) -> dict[str, Any]: for carrier in (request, event): if carrier is not None: try: setattr(carrier, ATTRIBUTE_NAME, state) except Exception: pass return state def read_context_state(request: Any | None = None, event: Any | None = None, *, fixture_version: str = "1") -> dict[str, Any] | None: for carrier in (request, event): state = consume_context_state(getattr(carrier, ATTRIBUTE_NAME, None) if carrier is not None else None, fixture_version=fixture_version) if state is not None: attach_context_state(state, request, event) return state return None def _refresh(state: dict[str, Any]) -> None: if state["phase"] == "invalid" or state["finalized"]: return completed = set(state["completed_layers"]) state["phase"] = "safety_ready" if "safety" in completed else "memory_ready" if "memory" in completed else "companion_ready" if set(_CORE).issubset(completed) else "initialized" def _open(state: dict[str, Any]) -> bool: return consume_context_state(state) is not None and state.get("phase") != "invalid" and not state.get("finalized") def complete_layer(state: dict[str, Any], layer: str) -> dict[str, Any]: if not _open(state): return state if layer not in LAYERS: return _invalid(state, "layer_invalid") if layer not in state["completed_layers"]: state["completed_layers"].append(layer) state["completed_layers"].sort(key=LAYERS.index) _refresh(state); return state def register_fragment(state: dict[str, Any], *, key: Any, layer: str, source: Any = "", trust_level: str = "T2", content: Any = None, content_hash: Any = "", chars: Any = None, status: Any = "allowed") -> dict[str, Any]: if not _open(state): return state if layer not in LAYERS or trust_level not in TRUST_LEVELS: return _invalid(state, "fragment_invalid") raw = "" if content is None else str(content) try: size = max(0, int(len(raw) if chars is None else chars)) except (TypeError, ValueError): return _invalid(state, "fragment_chars_invalid") item = {"key": _text(key, 120) or "fragment", "layer": layer, "source": _text(source, 120), "trust_level": trust_level, "content_hash": _text(content_hash, 128) or hashlib.sha256(raw.encode("utf-8")).hexdigest(), "chars": size, "status": _text(status, 40) or "allowed"} for old in state["fragments"]: if old == item: return state if old.get("key") == item["key"]: return _invalid(state, "fragment_key_conflict") if len(state["fragments"]) >= MAX_FRAGMENTS: return _invalid(state, "fragment_limit") state["fragments"].append(item); return state def update_security(state: dict[str, Any], *, status: str | None = None, event_id: Any = None, memory_policy: str | None = None, tool_policy: str | None = None, response_policy: str | None = None, reason_codes: Any = None) -> dict[str, Any]: if not _open(state): return state security = state["security"] if status is not None: if status not in SECURITY_STATUSES: return _invalid(state, "security_status_invalid") security["status"] = status for key, value in (("memory_policy", memory_policy), ("tool_policy", tool_policy), ("response_policy", response_policy)): if value is not None: if value not in POLICIES: return _invalid(state, "security_policy_invalid") security[key] = value if event_id is not None: security["event_id"] = _text(event_id, 180) codes = [reason_codes] if isinstance(reason_codes, str) else (reason_codes or []) if not isinstance(codes, (list, tuple, set)): return _invalid(state, "reason_codes_invalid") for code in codes: if not isinstance(code, str) or _CODE_RE.fullmatch(code) is None: return _invalid(state, "reason_code_invalid") if code not in security["reason_codes"] and len(security["reason_codes"]) < MAX_REASON_CODES: security["reason_codes"].append(code) return state def finalize_state(state: dict[str, Any]) -> dict[str, Any]: if not _open(state): return state if set(LAYERS).issubset(set(state["completed_layers"])): state["phase"], state["finalized"] = "finalized", True else: _error(state, "finalize_pending_layers") return state def project_context_state(state: dict[str, Any] | None) -> dict[str, Any] | None: state = consume_context_state(state) if state is None: return None return deepcopy({key: state[key] for key in ("contract_name", "contract_version", "contract_fingerprint", "request_id", "session_id", "scope", "created_at", "phase", "completed_layers", "fragments", "security", "errors", "finalized")}) def infer_context_layer(key: Any = "", source: Any = "") -> str: text = f"{key or ''} {source or ''}".lower() if any(token in text for token in ("memory", "recall")): return "memory" if any(token in text for token in ("safety", "guard", "tool", "tts", "privacy", "sanitize")): return "safety" if any(token in text for token in ("persona", "reply.style", "identity", "character")): return "persona" if any(token in text for token in ("private.context", "preferred_address", "preferred address", "relationship", "nickname", "person", "user.")): return "person" if any(token in text for token in ("runtime", "state", "schedule", "temporal", "weather", "food", "agenda", "time")): return "runtime" return "scene"