androidctl 0.1.0__py3-none-any.whl

androidctld/refs/repair.py

@@ -0,0 +1,284 @@
+"""Internal ref repair decisions and diagnostic conversion."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from androidctld.artifacts.models import ScreenArtifacts
+from androidctld.artifacts.screen_lookup import lookup_source_screen_artifact
+from androidctld.commands.results import screen_summary
+from androidctld.errors import DaemonError, DaemonErrorCode
+from androidctld.refs.models import RefBinding, RefRepairSourceSignature
+from androidctld.refs.service import (
+    repair_source_signature_to_current_snapshot,
+    source_signature_from_artifact_payload,
+    source_signature_from_binding,
+)
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.runtime.screen_state import current_compiled_screen
+from androidctld.schema.base import dump_api_model
+from androidctld.semantics.public_models import PublicScreen
+
+
+class RepairDecisionStatus(str, Enum):
+    RESOLVED = "resolved"
+    LIVE_REF_MISSING = "live_ref_missing"
+    SOURCE_UNAVAILABLE = "source_unavailable"
+    INVALID_ARTIFACT = "invalid_artifact"
+    REPAIR_FAILED = "repair_failed"
+
+
+_DIAGNOSTIC_SOURCE_ARTIFACT_STATUSES = {
+    RepairDecisionStatus.SOURCE_UNAVAILABLE,
+    RepairDecisionStatus.INVALID_ARTIFACT,
+    RepairDecisionStatus.REPAIR_FAILED,
+}
+
+
+@dataclass(frozen=True)
+class RepairDecision:
+    ref: str | None
+    source_screen_id: str | None
+    status: RepairDecisionStatus
+    binding: RefBinding | None = None
+    source_signature: RefRepairSourceSignature | None = None
+
+    @property
+    def is_resolved(self) -> bool:
+        return self.status == RepairDecisionStatus.RESOLVED
+
+    @property
+    def diagnostic_source_artifact_status(self) -> str | None:
+        if self.status not in _DIAGNOSTIC_SOURCE_ARTIFACT_STATUSES:
+            return None
+        return self.status.value
+
+
+def resolved_repair_decision(
+    *,
+    ref: str,
+    source_screen_id: str,
+    binding: RefBinding,
+    source_signature: RefRepairSourceSignature | None = None,
+) -> RepairDecision:
+    return RepairDecision(
+        ref=ref,
+        source_screen_id=source_screen_id,
+        status=RepairDecisionStatus.RESOLVED,
+        binding=binding,
+        source_signature=source_signature,
+    )
+
+
+def resolved_source_signature_decision(
+    *,
+    ref: str,
+    source_screen_id: str,
+    source_signature: RefRepairSourceSignature,
+) -> RepairDecision:
+    return RepairDecision(
+        ref=ref,
+        source_screen_id=source_screen_id,
+        status=RepairDecisionStatus.RESOLVED,
+        source_signature=source_signature,
+    )
+
+
+def failed_repair_decision(
+    *,
+    ref: str | None,
+    source_screen_id: str | None,
+) -> RepairDecision:
+    return RepairDecision(
+        ref=ref,
+        source_screen_id=source_screen_id,
+        status=RepairDecisionStatus.REPAIR_FAILED,
+    )
+
+
+def resolve_ref_decision(
+    session: WorkspaceRuntime,
+    ref: str,
+    source_screen_id: str,
+) -> RepairDecision:
+    source_decision = resolve_source_binding_decision(
+        session,
+        ref,
+        source_screen_id,
+    )
+    if not source_decision.is_resolved:
+        return source_decision
+    if source_screen_id == session.current_screen_id:
+        return source_decision
+    source_signature = source_decision.source_signature
+    if source_signature is None:
+        raise RuntimeError("resolved source binding is missing its signature")
+    return repair_source_signature_decision(
+        session,
+        source_signature,
+        source_screen_id=source_screen_id,
+    )
+
+
+def resolve_source_binding_decision(
+    session: WorkspaceRuntime,
+    ref: str,
+    source_screen_id: str,
+) -> RepairDecision:
+    if source_screen_id == session.current_screen_id:
+        binding = session.ref_registry.get(ref)
+        if binding is None:
+            return RepairDecision(
+                ref=ref,
+                source_screen_id=source_screen_id,
+                status=RepairDecisionStatus.LIVE_REF_MISSING,
+            )
+        return resolved_repair_decision(
+            ref=ref,
+            source_screen_id=source_screen_id,
+            binding=binding,
+            source_signature=source_signature_from_binding(binding),
+        )
+
+    return load_source_artifact_binding_decision(session, ref, source_screen_id)
+
+
+def load_source_artifact_binding_decision(
+    session: WorkspaceRuntime,
+    ref: str,
+    source_screen_id: str,
+) -> RepairDecision:
+    source_screen_lookup = lookup_source_screen_artifact(session, source_screen_id)
+    if source_screen_lookup.status == "not_found":
+        return RepairDecision(
+            ref=ref,
+            source_screen_id=source_screen_id,
+            status=RepairDecisionStatus.SOURCE_UNAVAILABLE,
+        )
+    if source_screen_lookup.status == "invalid_artifact":
+        return RepairDecision(
+            ref=ref,
+            source_screen_id=source_screen_id,
+            status=RepairDecisionStatus.INVALID_ARTIFACT,
+        )
+    payload = source_screen_lookup.payload
+    if payload is None or payload.screen_id != source_screen_id:
+        return RepairDecision(
+            ref=ref,
+            source_screen_id=source_screen_id,
+            status=RepairDecisionStatus.INVALID_ARTIFACT,
+        )
+    binding_payload = payload.repair_bindings.get(ref)
+    if binding_payload is None:
+        return RepairDecision(
+            ref=ref,
+            source_screen_id=source_screen_id,
+            status=RepairDecisionStatus.INVALID_ARTIFACT,
+        )
+    return resolved_source_signature_decision(
+        ref=ref,
+        source_screen_id=source_screen_id,
+        source_signature=source_signature_from_artifact_payload(ref, binding_payload),
+    )
+
+
+def repair_source_signature_decision(
+    session: WorkspaceRuntime,
+    source_signature: RefRepairSourceSignature,
+    *,
+    source_screen_id: str,
+) -> RepairDecision:
+    compiled_screen = current_compiled_screen(session)
+    if compiled_screen is None or session.latest_snapshot is None:
+        return failed_repair_decision(
+            ref=source_signature.ref,
+            source_screen_id=source_screen_id,
+        )
+    repaired_binding = repair_source_signature_to_current_snapshot(
+        source_signature,
+        compiled_screen=compiled_screen,
+        snapshot_id=session.latest_snapshot.snapshot_id,
+    )
+    if repaired_binding is None:
+        return failed_repair_decision(
+            ref=source_signature.ref,
+            source_screen_id=source_screen_id,
+        )
+    return resolved_repair_decision(
+        ref=source_signature.ref,
+        source_screen_id=source_screen_id,
+        binding=repaired_binding,
+    )
+
+
+def ref_repair_error(
+    decision: RepairDecision,
+    public_screen: PublicScreen | None = None,
+    artifacts: ScreenArtifacts | None = None,
+) -> DaemonError:
+    if decision.status == RepairDecisionStatus.LIVE_REF_MISSING:
+        return DaemonError(
+            code=DaemonErrorCode.REF_RESOLUTION_FAILED,
+            message="ref does not exist on the current screen",
+            retryable=False,
+            details={"ref": decision.ref},
+            http_status=200,
+        )
+    return ref_stale_error(
+        decision.ref,
+        public_screen=public_screen,
+        artifacts=artifacts,
+        source_screen_id=decision.source_screen_id,
+        source_artifact_status=decision.diagnostic_source_artifact_status,
+    )
+
+
+def ref_stale_error(
+    ref: str | None,
+    public_screen: PublicScreen | None = None,
+    artifacts: ScreenArtifacts | None = None,
+    *,
+    source_screen_id: str | None = None,
+    source_artifact_status: str | RepairDecisionStatus | None = None,
+) -> DaemonError:
+    artifact_payload = artifacts or ScreenArtifacts(screen_json=None)
+    normalized_status = _normalize_source_artifact_status(source_artifact_status)
+    details: dict[str, Any] = {
+        "ref": ref,
+        "screen": (
+            screen_summary(
+                public_screen,
+                artifact_payload,
+            )
+            if public_screen is not None
+            else None
+        ),
+        "artifacts": dump_api_model(artifact_payload),
+    }
+    if source_screen_id is not None:
+        details["sourceScreenId"] = source_screen_id
+    if normalized_status is not None:
+        details["sourceArtifactStatus"] = normalized_status
+    return DaemonError(
+        code=DaemonErrorCode.REF_STALE,
+        message="ref could not be repaired",
+        retryable=normalized_status in (None, RepairDecisionStatus.REPAIR_FAILED.value),
+        details=details,
+        http_status=200,
+    )
+
+
+def _normalize_source_artifact_status(
+    source_artifact_status: str | RepairDecisionStatus | None,
+) -> str | None:
+    if source_artifact_status is None:
+        return None
+    if isinstance(source_artifact_status, RepairDecisionStatus):
+        return source_artifact_status.value
+    if source_artifact_status in {
+        status.value for status in _DIAGNOSTIC_SOURCE_ARTIFACT_STATUSES
+    }:
+        return source_artifact_status
+    raise ValueError(f"unknown sourceArtifactStatus: {source_artifact_status}")

androidctld/refs/service.py

@@ -0,0 +1,422 @@
+"""Ref registry reconciliation and repair helpers."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from copy import deepcopy
+from dataclasses import dataclass
+
+from androidctld.artifacts.screen_payloads import RepairBindingPayload
+from androidctld.refs.models import (
+    NodeHandle,
+    RefBinding,
+    RefFingerprint,
+    RefRegistry,
+    RefRepairSourceSignature,
+    SemanticProfile,
+)
+from androidctld.runtime_policy import NON_NUMERIC_REF_SORT_BUCKET
+from androidctld.semantics.compiler import CompiledScreen, SemanticNode
+from androidctld.text_equivalence import canonical_text_key
+
+HIGH_CONFIDENCE_BUCKET = 2
+MEDIUM_CONFIDENCE_BUCKET = 1
+STRONG_BOUNDS_DISTANCE = 8
+GAP_THRESHOLD_ANCHORED = 2
+GAP_THRESHOLD_CONTEXTUAL = 3
+
+
+@dataclass(frozen=True)
+class RepairEvidence:
+    label_match: bool
+    resource_match: bool
+    class_match: bool
+    parent_match: bool
+    sibling_overlap: int
+    state_overlap: int
+    actions_overlap: int
+    bounds_distance: int
+
+    @property
+    def identity_anchor_count(self) -> int:
+        return int(self.label_match) + int(self.resource_match)
+
+    @property
+    def semantic_signal_count(self) -> int:
+        return (
+            int(self.sibling_overlap > 0)
+            + int(self.state_overlap > 0)
+            + int(self.actions_overlap > 0)
+            + int(self.strong_bounds_match)
+        )
+
+    @property
+    def corroboration_count(self) -> int:
+        return (
+            int(self.class_match)
+            + int(self.parent_match)
+            + int(self.sibling_overlap > 0)
+            + int(self.state_overlap > 0)
+            + int(self.actions_overlap > 0)
+            + int(self.strong_bounds_match)
+        )
+
+    @property
+    def strong_bounds_match(self) -> bool:
+        return self.bounds_distance <= STRONG_BOUNDS_DISTANCE
+
+    @property
+    def contextual_anchor(self) -> bool:
+        return self.class_match and self.parent_match and self.semantic_signal_count > 0
+
+
+@dataclass(frozen=True)
+class RepairConfidence:
+    bucket: int
+    score: int
+    evidence: RepairEvidence
+
+    @property
+    def sort_key(self) -> tuple[int, int, int, int, int, int, int, int]:
+        return (
+            self.bucket,
+            self.score,
+            self.evidence.identity_anchor_count,
+            self.evidence.corroboration_count,
+            self.evidence.sibling_overlap,
+            self.evidence.state_overlap,
+            self.evidence.actions_overlap,
+            -self.evidence.bounds_distance,
+        )
+
+    @property
+    def is_high_confidence(self) -> bool:
+        return self.bucket >= HIGH_CONFIDENCE_BUCKET
+
+
+@dataclass(frozen=True)
+class RefReconcileResult:
+    registry: RefRegistry
+    compiled_screen: CompiledScreen
+
+
+class RefRegistryBuilder:
+    def finalize_compiled_screen(
+        self,
+        *,
+        compiled_screen: CompiledScreen,
+        snapshot_id: int,
+        previous_registry: RefRegistry | None,
+    ) -> RefReconcileResult:
+        finalized_compiled_screen = deepcopy(compiled_screen)
+        registry = self.reconcile(
+            compiled_screen=finalized_compiled_screen,
+            snapshot_id=snapshot_id,
+            previous_registry=previous_registry,
+        )
+        return RefReconcileResult(
+            registry=registry,
+            compiled_screen=finalized_compiled_screen,
+        )
+
+    def reconcile(
+        self,
+        compiled_screen: CompiledScreen,
+        snapshot_id: int,
+        previous_registry: RefRegistry | None,
+    ) -> RefRegistry:
+        clear_candidate_refs(compiled_screen)
+        registry = RefRegistry()
+        candidates = list(compiled_screen.ref_candidates())
+        remaining_candidates = list(candidates)
+        used_refs = set()
+
+        if previous_registry is not None:
+            for binding in sorted(
+                previous_registry.bindings.values(),
+                key=lambda item: ref_sort_key(item.ref),
+            ):
+                match = best_candidate_for_binding(binding, remaining_candidates)
+                if match is None:
+                    continue
+                candidate, _ = match
+                candidate.ref = binding.ref
+                used_refs.add(binding.ref)
+                registry.bindings[binding.ref] = binding_for_candidate(
+                    ref=binding.ref,
+                    candidate=candidate,
+                    snapshot_id=snapshot_id,
+                    reused=True,
+                )
+                remaining_candidates.remove(candidate)
+
+        next_index = 1
+        for candidate in candidates:
+            if candidate.ref:
+                continue
+            while f"n{next_index}" in used_refs:
+                next_index += 1
+            ref = f"n{next_index}"
+            candidate.ref = ref
+            used_refs.add(ref)
+            registry.bindings[ref] = binding_for_candidate(
+                ref=ref,
+                candidate=candidate,
+                snapshot_id=snapshot_id,
+                reused=False,
+            )
+        return registry
+
+
+def clear_candidate_refs(compiled_screen: CompiledScreen) -> None:
+    for candidate in compiled_screen.ref_candidates():
+        candidate.ref = ""
+
+
+def binding_for_candidate(
+    ref: str,
+    candidate: SemanticNode,
+    snapshot_id: int,
+    reused: bool,
+) -> RefBinding:
+    return RefBinding(
+        ref=ref,
+        handle=NodeHandle(
+            snapshot_id=snapshot_id,
+            rid=candidate.raw_rid,
+        ),
+        fingerprint=fingerprint_for_candidate(candidate),
+        semantic_profile=SemanticProfile(
+            state=tuple(candidate.state),
+            actions=tuple(candidate.actions),
+        ),
+        reused=reused,
+    )
+
+
+def fingerprint_for_candidate(candidate: SemanticNode) -> RefFingerprint:
+    return RefFingerprint(
+        role=candidate.role,
+        normalized_label=canonical_text_key(candidate.label),
+        resource_id=canonical_text_key(candidate.resource_id),
+        class_name=canonical_text_key(candidate.class_name),
+        parent_role=canonical_text_key(candidate.parent_role),
+        parent_label=canonical_text_key(candidate.parent_label),
+        sibling_labels=tuple(
+            canonical_text_key(label)
+            for label in candidate.sibling_labels
+            if canonical_text_key(label)
+        ),
+        relative_bounds=candidate.relative_bounds,
+    )
+
+
+def best_candidate_for_binding(
+    binding: RefBinding, candidates: Sequence[SemanticNode]
+) -> tuple[SemanticNode, RepairConfidence] | None:
+    return best_candidate_for_source_signature(
+        source_signature_from_binding(binding),
+        candidates,
+    )
+
+
+def best_candidate_for_source_signature(
+    source: RefRepairSourceSignature,
+    candidates: Sequence[SemanticNode],
+) -> tuple[SemanticNode, RepairConfidence] | None:
+    scored: list[tuple[RepairConfidence, str, SemanticNode]] = []
+    for candidate in candidates:
+        confidence = candidate_match_confidence(source, candidate)
+        if confidence is None:
+            continue
+        scored.append((confidence, candidate.raw_rid, candidate))
+    if not scored:
+        return None
+    scored.sort(key=lambda item: (item[0].sort_key, item[1]), reverse=True)
+    best_confidence, _, best_candidate = scored[0]
+    if not best_confidence.is_high_confidence:
+        return None
+    if len(scored) > 1 and repair_gap_too_small(best_confidence, scored[1][0]):
+        return None
+    return best_candidate, best_confidence
+
+
+def candidate_match_confidence(
+    source: RefRepairSourceSignature, candidate: SemanticNode
+) -> RepairConfidence | None:
+    fingerprint = source.fingerprint
+    candidate_fingerprint = fingerprint_for_candidate(candidate)
+    if candidate_fingerprint.role != fingerprint.role:
+        return None
+
+    label_match = (
+        candidate_fingerprint.normalized_label == fingerprint.normalized_label
+        and bool(fingerprint.normalized_label)
+    )
+    resource_match = (
+        candidate_fingerprint.resource_id == fingerprint.resource_id
+        and bool(fingerprint.resource_id)
+    )
+    class_match = candidate_fingerprint.class_name == fingerprint.class_name and bool(
+        fingerprint.class_name
+    )
+    parent_match = (
+        candidate_fingerprint.parent_role == fingerprint.parent_role
+        and candidate_fingerprint.parent_label == fingerprint.parent_label
+        and bool(fingerprint.parent_role or fingerprint.parent_label)
+    )
+    sibling_overlap = len(
+        set(candidate_fingerprint.sibling_labels).intersection(
+            fingerprint.sibling_labels
+        )
+    )
+    bounds_distance = bounds_distance_score(
+        candidate_fingerprint.relative_bounds, fingerprint.relative_bounds
+    )
+    state_overlap = set_overlap(
+        source.state,
+        candidate.state,
+    )
+    actions_overlap = set_overlap(
+        source.actions,
+        candidate.actions,
+    )
+    evidence = RepairEvidence(
+        label_match=label_match,
+        resource_match=resource_match,
+        class_match=class_match,
+        parent_match=parent_match,
+        sibling_overlap=sibling_overlap,
+        state_overlap=state_overlap,
+        actions_overlap=actions_overlap,
+        bounds_distance=bounds_distance,
+    )
+    if not (evidence.identity_anchor_count or evidence.contextual_anchor):
+        return None
+
+    bucket = confidence_bucket(evidence)
+    if bucket is None:
+        return None
+    return RepairConfidence(
+        bucket=bucket,
+        score=confidence_score(evidence),
+        evidence=evidence,
+    )
+
+
+def source_signature_from_binding(binding: RefBinding) -> RefRepairSourceSignature:
+    return RefRepairSourceSignature(
+        ref=binding.ref,
+        fingerprint=binding.fingerprint,
+        state=binding.semantic_profile.state,
+        actions=binding.semantic_profile.actions,
+    )
+
+
+def source_signature_from_artifact_payload(
+    ref: str,
+    payload: RepairBindingPayload,
+) -> RefRepairSourceSignature:
+    return RefRepairSourceSignature(
+        ref=ref,
+        fingerprint=RefFingerprint(
+            role=payload.fingerprint.role,
+            normalized_label=payload.fingerprint.normalized_label,
+            resource_id=payload.fingerprint.resource_id,
+            class_name=payload.fingerprint.class_name,
+            parent_role=payload.fingerprint.parent_role,
+            parent_label=payload.fingerprint.parent_label,
+            sibling_labels=payload.fingerprint.sibling_labels,
+            relative_bounds=payload.fingerprint.relative_bounds,
+        ),
+        state=payload.semantic_profile.state,
+        actions=payload.semantic_profile.actions,
+    )
+
+
+def repair_source_signature_to_current_snapshot(
+    source: RefRepairSourceSignature,
+    *,
+    compiled_screen: CompiledScreen,
+    snapshot_id: int,
+) -> RefBinding | None:
+    match = best_candidate_for_source_signature(
+        source,
+        compiled_screen.ref_candidates(),
+    )
+    if match is None:
+        return None
+    candidate, _ = match
+    return binding_for_candidate(
+        ref=source.ref,
+        candidate=candidate,
+        snapshot_id=snapshot_id,
+        reused=True,
+    )
+
+
+def bounds_distance_score(
+    left: tuple[int, int, int, int], right: tuple[int, int, int, int]
+) -> int:
+    return sum(abs(a - b) for a, b in zip(left, right, strict=True))
+
+
+def set_overlap(left: Sequence[str], right: Sequence[str]) -> int:
+    normalized_left = {
+        canonical_text_key(value) for value in left if canonical_text_key(value)
+    }
+    normalized_right = {
+        canonical_text_key(value) for value in right if canonical_text_key(value)
+    }
+    return len(normalized_left.intersection(normalized_right))
+
+
+def confidence_bucket(evidence: RepairEvidence) -> int | None:
+    if evidence.identity_anchor_count >= 2:
+        return HIGH_CONFIDENCE_BUCKET
+    if evidence.identity_anchor_count == 1:
+        if evidence.semantic_signal_count >= 1 or evidence.corroboration_count >= 2:
+            return HIGH_CONFIDENCE_BUCKET
+        return MEDIUM_CONFIDENCE_BUCKET
+    if evidence.contextual_anchor:
+        if evidence.semantic_signal_count >= 2 and evidence.corroboration_count >= 4:
+            return HIGH_CONFIDENCE_BUCKET
+        return MEDIUM_CONFIDENCE_BUCKET
+    return None
+
+
+def confidence_score(evidence: RepairEvidence) -> int:
+    return (
+        evidence.identity_anchor_count * 8
+        + int(evidence.class_match) * 3
+        + int(evidence.parent_match) * 3
+        + min(evidence.sibling_overlap, 2) * 2
+        + min(evidence.state_overlap, 2) * 2
+        + min(evidence.actions_overlap, 2) * 2
+        + int(evidence.strong_bounds_match) * 2
+    )
+
+
+def repair_gap_too_small(
+    best_confidence: RepairConfidence,
+    runner_up: RepairConfidence,
+) -> bool:
+    if runner_up.bucket != best_confidence.bucket:
+        return False
+    gap_threshold = (
+        GAP_THRESHOLD_ANCHORED
+        if best_confidence.evidence.identity_anchor_count > 0
+        else GAP_THRESHOLD_CONTEXTUAL
+    )
+    return (best_confidence.score - runner_up.score) < gap_threshold
+
+
+_REF_RE = re.compile(r"^n(\d+)$")
+
+
+def ref_sort_key(ref: str) -> tuple[int, str]:
+    match = _REF_RE.match(ref)
+    if match is None:
+        return (NON_NUMERIC_REF_SORT_BUCKET, ref)
+    return (int(match.group(1)), ref)

androidctld/rendering/__init__.py

@@ -0,0 +1 @@
+"""Daemon-owned public rendering helpers."""