"""Stable, serializable window evidence used by dialog supervision.""" from __future__ import annotations from dataclasses import asdict, dataclass from enum import Enum import hashlib import json import re from typing import Any class DialogPhase(str, Enum): PCB_STARTING = "PCB_STARTING" LICENSE_ACQUISITION = "LICENSE_ACQUISITION" DATABASE_RECOVERY = "DATABASE_RECOVERY" DOCUMENT_ATTACH = "DOCUMENT_ATTACH" IDENTITY_CHECK = "IDENTITY_CHECK" PROJECT_INTEGRATION = "PROJECT_INTEGRATION" VALIDATE = "VALIDATE" SAVE = "SAVE" CLOSE = "CLOSE" POST_VERIFY_STATUS = "POST_VERIFY_STATUS" @dataclass(frozen=True) class ControlSnapshot: handle: int control_id: int class_name: str name: str automation_id: str = "" control_type: str = "" enabled: bool = True selected: bool = False checked: bool = False patterns: tuple[str, ...] = () @classmethod def from_record(cls, record: dict[str, Any]) -> "ControlSnapshot": values = dict(record) values["patterns"] = tuple(values.get("patterns", ())) return cls(**values) @dataclass(frozen=True) class WindowSnapshot: hwnd: int pid: int process_name: str process_role: str window_class: str title: str phase: DialogPhase controls: tuple[ControlSnapshot, ...] owner_hwnd: int = 0 diagnostics: tuple[str, ...] = () @property def texts(self) -> tuple[str, ...]: return tuple(control.name for control in self.controls if control.name.strip()) @property def signature(self) -> tuple[object, ...]: return ( self.title, tuple((control.control_id, control.class_name, control.name, control.enabled, control.checked, control.selected) for control in self.controls), ) def to_record(self) -> dict[str, Any]: record = asdict(self) record["phase"] = self.phase.value return record @classmethod def from_record(cls, record: dict[str, Any]) -> "WindowSnapshot": values = dict(record) values["phase"] = DialogPhase(values["phase"]) values["controls"] = tuple(ControlSnapshot.from_record(item) for item in values.get("controls", ())) values["diagnostics"] = tuple(values.get("diagnostics", ())) return cls(**values) @dataclass(frozen=True) class RuleDecision: rule_id: str = "" category: str = "" action: str = "" channels: tuple[str, ...] = () target: tuple[tuple[str, object], ...] = () postcondition: str = "" error_code: str = "" detail: str = "" _GUID = re.compile(r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b", re.I) _WINDOWS_PATH = re.compile(r"(?i)(?:[a-z]:\\|\\\\)[^\s|]+") _NUMBER = re.compile(r"\b\d+(?:\.\d+)?\b") _SPACE = re.compile(r"\s+") def normalize_text(value: str) -> str: text = str(value or "").casefold() text = _GUID.sub("", text) text = _WINDOWS_PATH.sub("", text) text = _NUMBER.sub("", text) return _SPACE.sub(" ", text).strip() def stable_fingerprint(snapshot: WindowSnapshot) -> str: controls = sorted( ( control.control_id, control.class_name.casefold(), normalize_text(control.name), control.automation_id.casefold(), control.control_type.casefold(), tuple(sorted(pattern.casefold() for pattern in control.patterns)), ) for control in snapshot.controls ) stable = { "phase": snapshot.phase.value, "process_name": snapshot.process_name.casefold(), "process_role": snapshot.process_role.casefold(), "window_class": snapshot.window_class.casefold(), "owned": bool(snapshot.owner_hwnd), "title": normalize_text(snapshot.title), "controls": controls, } payload = json.dumps(stable, ensure_ascii=False, sort_keys=True, separators=(",", ":")) return hashlib.sha256(payload.encode("utf-8")).hexdigest() def compatible_window_identity(expected: WindowSnapshot, actual: WindowSnapshot) -> bool: """Allow transient control-tree changes without accepting a new window.""" return ( expected.hwnd == actual.hwnd and expected.pid == actual.pid and expected.process_name.casefold() == actual.process_name.casefold() and expected.window_class.casefold() == actual.window_class.casefold() and normalize_text(expected.title) == normalize_text(actual.title) )