"""Private QA-branch contracts for the isolated SWA checkpoint. The formal action model deliberately does not import or apply this adapter: its forward path has no video tensors or answer-text loss. This module gives the future multimodal runtime a strict, cheap validation boundary and avoids the dangerous alternative of silently treating an incompatible QA checkpoint as an action checkpoint. """ from __future__ import annotations import hashlib from dataclasses import dataclass from pathlib import Path from typing import Any, Mapping QA_LORA_SHA256 = "259d4df38622f10effb532e7f5213b322252b564eb3dc6a97508c220a972a681" @dataclass(frozen=True) class QAPrivateKVConfig: """Configuration for a side QA branch, never for the action KV.""" enabled: bool = False checkpoint: str = "" expected_sha256: str = QA_LORA_SHA256 layers: int = 8 rank: int = 16 alpha: float = 16.0 targets: str = "full" max_pending_packets: int = 2 def validate(self) -> "QAPrivateKVConfig": if self.layers <= 0 or self.rank <= 0: raise ValueError("QA LoRA layers and rank must be positive") if self.alpha <= 0: raise ValueError("QA LoRA alpha must be positive") if self.targets not in {"qv", "attention", "full"}: raise ValueError(f"Unsupported QA LoRA target profile: {self.targets}") if self.max_pending_packets < 1: raise ValueError("max_pending_packets must be positive") if self.enabled and not self.checkpoint: raise ValueError("An enabled private QA branch requires a checkpoint") return self def sha256_file(path: str | Path, *, chunk_bytes: int = 1 << 20) -> str: """Hash a checkpoint without loading it into memory.""" digest = hashlib.sha256() with Path(path).expanduser().open("rb") as handle: while True: chunk = handle.read(chunk_bytes) if not chunk: break digest.update(chunk) return digest.hexdigest() def validate_qa_checkpoint( path: str | Path, *, expected_sha256: str | None = QA_LORA_SHA256, ) -> dict[str, Any]: """Validate existence, digest and flat LoRA tensor-key contract. Loading is intentionally deferred to the actual multimodal runtime. The returned metadata is sufficient for startup checks and provenance logs. """ resolved = Path(path).expanduser().resolve() if not resolved.is_file(): raise FileNotFoundError(f"QA LoRA checkpoint is missing: {resolved}") digest = sha256_file(resolved) if expected_sha256 and digest != expected_sha256: raise RuntimeError( "QA LoRA checkpoint SHA256 mismatch: " f"expected={expected_sha256} actual={digest} path={resolved}" ) tensor_count = None try: import torch state = torch.load(resolved, map_location="cpu", weights_only=True) if not isinstance(state, Mapping): raise TypeError(f"expected mapping, got {type(state).__name__}") keys = tuple(str(key) for key in state) if not keys or any( not (key.endswith(".down.weight") or key.endswith(".up.weight")) for key in keys ): raise ValueError("expected flat '.down/up.weight' LoRA keys") tensor_count = len(keys) except ImportError: # The validator remains usable in a CPU-only metadata environment. pass return { "path": str(resolved), "sha256": digest, "tensor_count": tensor_count, "private_kv": True, "writes_main_action_kv": False, }