openmd-cli 0.1.0__py3-none-any.whl

openmd/core/coverage.py

@@ -0,0 +1,163 @@
+"""Small reusable counters for collection coverage summaries.
+
+The helper intentionally keeps only bounded enums and integer counts.  It does
+not retain URLs, output paths, backend payloads, or other acquisition data, so
+platform summaries can safely serialize the result without leaking transient
+locators.
+"""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Mapping
+
+from .models import ContentItem, ExtractionComponent, TranscriptResult
+from .package_contract import package_source_level
+
+
+_ITEM_STATUSES = ("verified", "partial", "failed")
+_BLOCKING_COMPONENT_STATUSES = {"partial", "failed", "retryable", "auth_challenge"}
+_CONTENT_TYPES = ("text", "image_text", "video", "mixed")
+
+
+@dataclass
+class CollectionCoverage:
+    """Accumulate item outcomes and component provenance without identifiers."""
+
+    attempted: int = 0
+    skipped_existing: int = 0
+    terminal_gap_items: int = 0
+    retryable_items: int = 0
+    _item_statuses: Counter[str] = field(default_factory=Counter)
+    _component_statuses: dict[str, Counter[str]] = field(
+        default_factory=lambda: defaultdict(Counter)
+    )
+    _component_sources: dict[str, Counter[str]] = field(
+        default_factory=lambda: defaultdict(Counter)
+    )
+    _source_levels: Counter[str] = field(default_factory=Counter)
+
+    def record_result(
+        self,
+        result: TranscriptResult,
+        *,
+        skipped_existing: bool = False,
+        force_failed: bool = False,
+    ) -> None:
+        self.record(
+            status="failed" if force_failed else result.status,
+            components=result.normalized_components,
+            skipped_existing=skipped_existing,
+        )
+
+    def record_metadata(
+        self,
+        metadata: Mapping[str, Any],
+        *,
+        skipped_existing: bool = False,
+    ) -> None:
+        raw_components = metadata.get("components")
+        components = raw_components if isinstance(raw_components, list) else []
+        self.record(
+            status=str(metadata.get("status") or "failed"),
+            components=components,
+            skipped_existing=skipped_existing,
+        )
+
+    def record_failure(self) -> None:
+        self.record(status="failed", components=[])
+
+    def record(
+        self,
+        *,
+        status: str,
+        components: Iterable[ExtractionComponent | Mapping[str, Any]],
+        skipped_existing: bool = False,
+    ) -> None:
+        normalized_status = status if status in _ITEM_STATUSES else "failed"
+        self.attempted += 1
+        self._item_statuses[normalized_status] += 1
+        if skipped_existing:
+            self.skipped_existing += 1
+
+        has_terminal_gap = False
+        has_blocking_component = normalized_status == "failed"
+        for component in components:
+            component_id, component_status, source_level = _component_projection(component)
+            if not component_id:
+                continue
+            source_level = package_source_level(source_level)
+            self._component_statuses[component_id][component_status] += 1
+            self._component_sources[component_id][source_level] += 1
+            self._source_levels[source_level] += 1
+            has_terminal_gap = has_terminal_gap or component_status == "unavailable"
+            has_blocking_component = (
+                has_blocking_component
+                or component_status in _BLOCKING_COMPONENT_STATUSES
+            )
+
+        if has_terminal_gap:
+            self.terminal_gap_items += 1
+        if has_blocking_component:
+            self.retryable_items += 1
+
+    def as_dict(self) -> dict[str, Any]:
+        component_counts: dict[str, dict[str, int]] = {}
+        component_source_counts: dict[str, dict[str, int]] = {}
+        for component_id in sorted(self._component_statuses):
+            statuses = self._component_statuses[component_id]
+            component_counts[component_id] = {
+                "total": sum(statuses.values()),
+                **{key: int(value) for key, value in sorted(statuses.items())},
+            }
+            component_source_counts[component_id] = {
+                key: int(value)
+                for key, value in sorted(self._component_sources[component_id].items())
+            }
+
+        return {
+            "attempted": self.attempted,
+            "verified": int(self._item_statuses["verified"]),
+            "partial": int(self._item_statuses["partial"]),
+            "failed": int(self._item_statuses["failed"]),
+            "skipped_existing": self.skipped_existing,
+            "terminal_gaps": sum(
+                counts["unavailable"] for counts in self._component_statuses.values()
+            ),
+            "terminal_gap_items": self.terminal_gap_items,
+            "retryable": sum(
+                counts["retryable"] for counts in self._component_statuses.values()
+            ),
+            "retryable_items": self.retryable_items,
+            "component_counts": component_counts,
+            "component_source_counts": component_source_counts,
+            "source_counts": {
+                key: int(value) for key, value in sorted(self._source_levels.items())
+            },
+        }
+
+
+def collection_content_type_counts(items: Iterable[ContentItem]) -> dict[str, int]:
+    """Return stable text/image_text/video/mixed counts for discovered items."""
+    counts = Counter({key: 0 for key in _CONTENT_TYPES})
+    for item in items:
+        raw_kind = item.raw_meta.get("media_kind") if isinstance(item.raw_meta, dict) else None
+        kind = str(raw_kind or item.source_type or "mixed").strip().lower().replace("-", "_")
+        if kind in {"article", "document", "text_first", "text_only"}:
+            kind = "text"
+        if kind not in _CONTENT_TYPES:
+            kind = "mixed"
+        counts[kind] += 1
+    return {key: int(counts[key]) for key in _CONTENT_TYPES}
+
+
+def _component_projection(
+    component: ExtractionComponent | Mapping[str, Any],
+) -> tuple[str, str, str]:
+    if isinstance(component, ExtractionComponent):
+        return component.id, component.status, component.source_level
+    component_id = str(component.get("id") or "").strip()
+    status = str(component.get("status") or "failed").strip()
+    source_level = str(component.get("source_level") or "partial_extraction").strip()
+    return component_id, status, source_level

openmd/core/detector.py

@@ -0,0 +1,247 @@
+"""Conservative URL platform detector for Openmd V0 categories."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+
+PLATFORM_IDS: tuple[str, ...] = (
+    "bilibili",
+    "youtube",
+    "weixin",
+    "wechat_group",
+    "wechat_moments",
+    "qq_group",
+    "xiaoyuzhou",
+    "douyin",
+    "tiktok",
+    "xiaohongshu",
+    "xiaoe",
+    "x",
+    "feishu",
+    "web_article",
+    "generic_media",
+    "pdf",
+    "screenshot",
+)
+
+MEDIA_EXTENSIONS: tuple[str, ...] = (
+    ".mp4",
+    ".m4v",
+    ".mov",
+    ".webm",
+    ".mkv",
+    ".mp3",
+    ".m4a",
+    ".wav",
+    ".flac",
+    ".m3u8",
+)
+
+# Keep the legacy `pdf` platform identity for the approved PDF/Office lane.
+DOCUMENT_EXTENSIONS: tuple[str, ...] = (".pdf", ".docx", ".pptx", ".xlsx")
+
+IMAGE_TEXT_EXTENSIONS: tuple[str, ...] = (
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".bmp",
+)
+
+QQ_EXPORT_EXTENSIONS: tuple[str, ...] = (".json", ".html", ".txt")
+
+_BV_RE = re.compile(r"^BV[0-9A-Za-z]+$")
+_URL_RE = re.compile(r"https?://[^\s，。]+")
+
+
+def extract_first_url(input_value: str) -> str:
+    value = input_value.strip()
+    match = _URL_RE.search(value)
+    if not match:
+        return value
+    return match.group(0).rstrip(".,，。；;！!)）]")
+
+
+def _host_and_path(input_value: str) -> tuple[str, str]:
+    value = extract_first_url(input_value)
+    parse_value = value if "://" in value else f"https://{value}"
+    parsed = urlparse(parse_value)
+    return parsed.netloc.lower(), parsed.path.lower()
+
+
+def _host_endswith(host: str, suffixes: tuple[str, ...]) -> bool:
+    return any(host == suffix or host.endswith(f".{suffix}") for suffix in suffixes)
+
+
+def looks_like_media_url(input_value: str) -> bool:
+    _, path = _host_and_path(input_value)
+    return path.endswith(MEDIA_EXTENSIONS)
+
+
+def _path_for_extension_check(input_value: str) -> str:
+    value = extract_first_url(input_value)
+    parsed = urlparse(value)
+    if parsed.scheme == "file":
+        return parsed.path.lower()
+    if parsed.scheme in {"http", "https"}:
+        return parsed.path.lower()
+    return value.lower()
+
+
+def detect_platform(input_value: str, *, explicit_media: bool = False) -> str:
+    value = input_value.strip()
+    if explicit_media:
+        return "generic_media"
+    directory_platform = _local_directory_platform(value)
+    if directory_platform is not None:
+        return directory_platform
+    if _is_weixin_official_account_selector(value):
+        return "weixin"
+    if _is_wechat_moments_selector(value):
+        return "wechat_moments"
+    if _is_wechat_group_selector(value):
+        return "wechat_group"
+    if _is_qq_group_selector(value) or _looks_like_qq_export_path(value):
+        return "qq_group"
+    if _BV_RE.match(value):
+        return "bilibili"
+    if re.fullmatch(r"\d{15,20}", value):
+        return "douyin"
+
+    extension_path = _path_for_extension_check(value)
+    if extension_path.endswith(DOCUMENT_EXTENSIONS):
+        return "pdf"
+    if extension_path.endswith(IMAGE_TEXT_EXTENSIONS):
+        return "screenshot"
+    if extension_path.endswith(MEDIA_EXTENSIONS):
+        return "generic_media"
+
+    host, path = _host_and_path(value)
+    if _host_endswith(host, ("bilibili.com", "b23.tv")):
+        return "bilibili"
+    if _host_endswith(host, ("youtube.com", "youtu.be", "youtube-nocookie.com")):
+        return "youtube"
+    if host == "mp.weixin.qq.com":
+        return "weixin"
+    if _host_endswith(host, ("xiaoyuzhoufm.com",)):
+        return "xiaoyuzhou"
+    if _host_endswith(host, ("douyin.com", "iesdouyin.com")):
+        return "douyin"
+    if _host_endswith(host, ("tiktok.com",)):
+        return "tiktok"
+    if _host_endswith(host, ("xiaohongshu.com", "xhslink.com")):
+        return "xiaohongshu"
+    if _host_endswith(host, ("xet.citv.cn", "xet.pomoho.com", "xiaoeknow.com")) or "xiaoe" in host:
+        return "xiaoe"
+    if _host_endswith(host, ("x.com", "twitter.com")):
+        return "x"
+    if _host_endswith(host, ("feishu.cn", "larksuite.com")):
+        return "feishu"
+    if path.endswith(MEDIA_EXTENSIONS):
+        return "generic_media"
+    return "web_article"
+
+
+def _local_directory_platform(value: str) -> str | None:
+    path = _local_path_for_detection(value)
+    if path is None or not path.is_dir():
+        return None
+
+    seen_pdf = False
+    seen_image = False
+    seen_media = False
+    checked = 0
+    try:
+        for candidate in path.rglob("*"):
+            if not candidate.is_file():
+                continue
+            suffix = candidate.suffix.lower()
+            seen_pdf = seen_pdf or suffix in DOCUMENT_EXTENSIONS
+            seen_image = seen_image or suffix in IMAGE_TEXT_EXTENSIONS
+            seen_media = seen_media or suffix in MEDIA_EXTENSIONS
+            checked += 1
+            if checked >= 200 or seen_pdf:
+                break
+    except OSError:
+        return None
+
+    if seen_pdf:
+        return "pdf"
+    if seen_image:
+        return "screenshot"
+    if seen_media:
+        return "generic_media"
+    return None
+
+
+def _local_path_for_detection(value: str) -> Path | None:
+    parsed = urlparse(value)
+    if parsed.scheme in {"http", "https"}:
+        return None
+    if len(parsed.scheme) == 1 and len(value) >= 3 and value[1] == ":" and value[2] in {"\\", "/"}:
+        return Path(value)
+    if parsed.scheme == "file":
+        raw_path = unquote(parsed.path)
+        if parsed.netloc and not raw_path:
+            raw_path = parsed.netloc
+        if raw_path.startswith("/") and len(raw_path) >= 4 and raw_path[2] == ":":
+            raw_path = raw_path[1:]
+        return Path(raw_path)
+    if parsed.scheme:
+        return None
+    return Path(value)
+
+
+def _is_wechat_group_selector(value: str) -> bool:
+    parsed = urlparse(value.strip())
+    if parsed.scheme in {"wx", "wechat"} and parsed.netloc.lower() == "group":
+        return bool(parsed.path.strip("/"))
+    if parsed.scheme in {"wx-group", "wechat-group"}:
+        return bool(parsed.netloc or parsed.path.strip("/"))
+    return False
+
+
+def _is_weixin_official_account_selector(value: str) -> bool:
+    parsed = urlparse(value.strip())
+    if parsed.scheme in {"weixin", "wx-official", "wechat-official"}:
+        return bool(parsed.netloc or parsed.path.strip("/"))
+    if parsed.scheme == "wechat" and parsed.netloc.lower() in {
+        "official",
+        "official-account",
+        "oa",
+        "author",
+        "account",
+        "fakeid",
+        "biz",
+    }:
+        return bool(parsed.path.strip("/") or parsed.query.strip())
+    return False
+
+
+def _is_wechat_moments_selector(value: str) -> bool:
+    parsed = urlparse(value.strip())
+    if parsed.scheme in {"wx", "wechat"} and parsed.netloc.lower() in {"moments", "sns"}:
+        return bool(parsed.path.strip("/"))
+    if parsed.scheme in {"wx-moments", "wechat-moments"}:
+        return bool(parsed.netloc or parsed.path.strip("/"))
+    return False
+
+
+def _is_qq_group_selector(value: str) -> bool:
+    parsed = urlparse(value.strip())
+    if parsed.scheme == "qq" and parsed.netloc.lower() == "group":
+        return bool(parsed.path.strip("/"))
+    if parsed.scheme in {"qq-group", "qq_export", "qq-export"}:
+        return bool(parsed.netloc or parsed.path.strip("/"))
+    return False
+
+
+def _looks_like_qq_export_path(value: str) -> bool:
+    extension_path = _path_for_extension_check(value)
+    if not extension_path.endswith(QQ_EXPORT_EXTENSIONS):
+        return False
+    filename = extension_path.replace("\\", "/").rsplit("/", 1)[-1]
+    return "qq" in filename or "group-chat" in filename

openmd/core/doctor.py

@@ -0,0 +1,104 @@
+"""Safe local-only doctor projections for Openmd capability profiles."""
+
+from __future__ import annotations
+
+import importlib.util
+import shutil
+from typing import Any
+
+from .capabilities import validate_capability_manifest
+
+
+DOCTOR_PROFILES = ("all", "core", "web", "media", "documents", "authenticated-social", "tools")
+
+
+def _module_available(name: str) -> bool:
+    try:
+        return importlib.util.find_spec(name) is not None
+    except (ImportError, ValueError):
+        return False
+
+
+def _media_diagnostics() -> dict[str, Any]:
+    from openmd.runtime.interpreters import select_asr_runtime
+    from openmd.runtime.models import configured_models
+
+    runtime = select_asr_runtime()
+    ffmpeg_available = shutil.which("ffmpeg") is not None
+    ready = bool(runtime.probe.get("ready")) and ffmpeg_available
+    next_action = "Local CUDA ASR runtime and models are ready" if ready else runtime.reason
+    if not ffmpeg_available:
+        next_action = "Install ffmpeg and make it available on PATH, then rerun openmd doctor --profile media"
+    return {
+        "ffmpeg_on_path": ffmpeg_available,
+        "local_asr_dependency": _module_available("faster_whisper"),
+        "asr_runtime": runtime.as_dict(),
+        "models": {key: model.as_dict() for key, model in configured_models().items()},
+        "ready": ready,
+        "next_action": next_action,
+    }
+
+
+def _document_diagnostics() -> dict[str, Any]:
+    from openmd.ocr.config import settings
+    from openmd.ocr.layout import probe_layout
+    from openmd.ocr.office import soffice_path
+    from openmd.ocr.ollama import probe_ollama
+    from openmd.runtime.gpu_lock import gpu_lock_path
+    from openmd.runtime.gpu_quarantine import quarantine_path
+
+    try:
+        ollama = probe_ollama(settings())
+    except ValueError as exc:
+        ollama = {"reachable": False, "ready": False, "models": {}, "error_code": getattr(exc, "code", "ocr_setting_invalid")}
+    layout = probe_layout()
+    layout.update({"device": "cpu", "cpu_only": True, "cuda_visible_policy": "reject", "gpu_lease_inherited": False})
+    dependencies = {"pymupdf_available": _module_available("pymupdf"), "pillow_available": _module_available("PIL"), "numpy_available": _module_available("numpy")}
+    ready = all(dependencies.values()) and ollama["ready"] and layout["ready"]
+    return {"markitdown_available": _module_available("markitdown"), "ocr_dependency_available": _module_available("rapidocr_onnxruntime"), **dependencies, "ollama": ollama, "layout_runtime": layout, "libreoffice_available": soffice_path() is not None, "gpu_lock": {"path": str(gpu_lock_path()), "implementation": "OS file lock shared with ASR", "crash_recovery": "OS releases lease; persistent file is reused", "quarantine_exists": quarantine_path().exists(), "quarantine_recovery": "read-only wait for empty /api/ps; never unload other clients", "marker_only_reset": "openmd doctor --clear-gpu-quarantine"}, "ready": ready, "network_access": "configured_ollama_metadata_only", "next_action": "Document OCR dependencies are ready" if ready else "Start Ollama yourself and provide existing models / configure ocr_python and model_roots; Openmd does not install, download, pull or start services."}
+
+
+def build_doctor_report(profile: str) -> dict[str, Any]:
+    if profile not in DOCTOR_PROFILES:
+        raise ValueError(f"unsupported doctor profile: {profile}")
+    try:
+        validate_capability_manifest()
+        manifest_valid = True
+    except ValueError:
+        manifest_valid = False
+    diagnostics: dict[str, Any] = {
+        "profile": profile,
+        "manifest_valid": manifest_valid,
+        "network_access": "not_probed",
+        "private_session_state": "not_read",
+        "account_actions": "not_performed",
+        "ready": manifest_valid,
+    }
+    if profile == "all":
+        diagnostics.update(_media_diagnostics())
+        diagnostics["openmd_on_path"] = shutil.which("openmd") is not None
+        diagnostics["ready"] = bool(diagnostics["ready"] and manifest_valid)
+        diagnostics["optional_profiles"] = {
+            "web": {"opencli_on_path": shutil.which("opencli") is not None, "network_gate": "explicit_opt_in"},
+            "documents": _document_diagnostics(),
+        }
+    elif profile == "core":
+        diagnostics.update({"openmd_on_path": shutil.which("openmd") is not None})
+    elif profile == "web":
+        diagnostics.update({"opencli_on_path": shutil.which("opencli") is not None, "network_gate": "explicit_opt_in"})
+    elif profile == "media":
+        diagnostics.update(_media_diagnostics())
+        diagnostics["ready"] = bool(diagnostics["ready"] and manifest_valid)
+    elif profile == "documents":
+        diagnostics.update(_document_diagnostics())
+        diagnostics["ready"] = manifest_valid and diagnostics["ready"]
+    elif profile == "tools":
+        # Populated by the tool-card diagnostics without executing a command.
+        from openmd.routing.providers import doctor_tools
+
+        tool_report = doctor_tools()
+        diagnostics["tools"] = tool_report
+        diagnostics["ready"] = manifest_valid and bool(tool_report.get("ok", False))
+    else:
+        diagnostics.update({"session_owner": "browser_platform_or_sidecar", "private_session_probe": False})
+    return diagnostics

openmd/core/execution_policy.py

@@ -0,0 +1,164 @@
+"""Execution identity and compact package writer ownership rules."""
+
+from __future__ import annotations
+
+import errno
+import hashlib
+import json
+import os
+import tempfile
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+FINGERPRINT_CONTRACT_VERSION = "openmd.low-token.v1"
+COMPACT_LOCK_VERSION = "openmd.compact-lock.v2"
+
+
+def execution_fingerprint(
+    *,
+    requested_profile: str | None,
+    requested_modalities: tuple[str, ...],
+    provider_chain: tuple[str, ...],
+    backend_override: str | None,
+    model: str | None,
+    language: str | None,
+    authorization_flags: dict[str, bool] | None = None,
+    temporary_url: str | None = None,
+    extraction_contract: dict[str, object] | None = None,
+    effective_config: dict[str, object] | None = None,
+) -> str:
+    """Return a stable fingerprint without credentials, gates, or transient locators."""
+    del authorization_flags, temporary_url
+    payload = {
+        "contract_version": FINGERPRINT_CONTRACT_VERSION,
+        "requested_profile": requested_profile,
+        "requested_modalities": list(requested_modalities),
+        "provider_chain": list(provider_chain),
+        "backend_override": backend_override,
+        "model": model,
+        "language": language,
+        "extraction_contract": extraction_contract,
+        "effective_config": effective_config,
+    }
+    encoded = json.dumps(payload, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def require_matching_fingerprint(metadata: dict[str, object], fingerprint: str) -> str | None:
+    stored = metadata.get("execution_fingerprint")
+    if not isinstance(stored, str) or not stored:
+        return "execution_fingerprint_missing"
+    if stored != fingerprint:
+        return "execution_fingerprint_mismatch"
+    return None
+
+
+@dataclass
+class CompactOutputLock:
+    path: Path
+    run_id: str
+    _owner_token: str = field(default="", repr=False)
+    _guard_descriptor: int | None = field(default=None, repr=False)
+
+    @classmethod
+    def acquire(cls, out_dir: str | Path, run_id: str) -> "CompactOutputLock":
+        if not isinstance(run_id, str) or not run_id or len(run_id) > 128 or not run_id.isascii():
+            raise ValueError("compact lock requires a bounded ASCII run id")
+        path = Path(out_dir) / ".openmd-compact.lock"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # Never unlink the guard: replacing its inode would let two writers lock
+        # different files. The OS releases this descriptor's lock after a crash.
+        descriptor = os.open(path.parent / ".openmd-compact.guard", os.O_RDWR | os.O_CREAT, 0o600)
+        try:
+            _acquire_guard(descriptor, path)
+            existing = _read_owner(path)
+            token = uuid.uuid4().hex
+            owner = {"schema_version": COMPACT_LOCK_VERSION, "run_id": run_id, "owner_token": token}
+            _install_owner(path, owner, replace_existing=existing is not None)
+            return cls(path=path, run_id=run_id, _owner_token=token, _guard_descriptor=descriptor)
+        except BaseException:
+            os.close(descriptor)
+            raise
+
+    def release(self) -> None:
+        descriptor = self._guard_descriptor
+        if descriptor is None:
+            return
+        try:
+            owner = _read_owner(self.path)
+            if owner and owner["run_id"] == self.run_id and owner["owner_token"] == self._owner_token:
+                self.path.unlink()
+        except OSError:
+            # Preserve missing/changed/unknown ownership records. Closing the
+            # guard is still mandatory, including a failed normal cleanup.
+            pass
+        finally:
+            self._guard_descriptor = None
+            os.close(descriptor)
+
+
+def _acquire_guard(descriptor: int, owner_path: Path) -> None:
+    try:
+        if os.name == "nt":
+            import msvcrt
+
+            os.lseek(descriptor, 0, os.SEEK_SET)
+            msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError as error:
+        if error.errno in {errno.EACCES, errno.EAGAIN, errno.EDEADLK}:
+            raise FileExistsError(errno.EEXIST, "compact output has a live owner", str(owner_path)) from None
+        raise
+
+
+def _read_owner(path: Path) -> dict[str, str] | None:
+    try:
+        with path.open("rb") as stream:
+            raw = stream.read(4097)
+    except FileNotFoundError:
+        return None
+    try:
+        owner = json.loads(raw) if len(raw) <= 4096 else None
+    except (ValueError, UnicodeError):
+        owner = None
+    if (
+        not isinstance(owner, dict)
+        or set(owner) != {"schema_version", "run_id", "owner_token"}
+        or owner.get("schema_version") != COMPACT_LOCK_VERSION
+        or not isinstance(owner.get("run_id"), str)
+        or not 0 < len(owner["run_id"]) <= 128
+        or not owner["run_id"].isascii()
+        or not isinstance(owner.get("owner_token"), str)
+        or len(owner["owner_token"]) != 32
+        or any(char not in "0123456789abcdef" for char in owner["owner_token"])
+    ):
+        # Legacy UUID-only locks did not hold this guard, so acquiring it cannot
+        # establish that their owner is dead. Unknown/torn records also stay put.
+        raise FileExistsError(errno.EEXIST, "compact output has an unknown ownership record", str(path))
+    return owner
+
+
+def _install_owner(path: Path, owner: dict[str, str], *, replace_existing: bool) -> None:
+    descriptor, temporary_name = tempfile.mkstemp(prefix=".openmd-compact-owner-", suffix=".tmp", dir=path.parent)
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(json.dumps(owner, separators=(",", ":")).encode("ascii"))
+            stream.flush()
+            os.fsync(stream.fileno())
+        if replace_existing:
+            # The guard proves this validated v2 owner is abandoned. Keep the
+            # canonical path present while replacing it so legacy O_EXCL users
+            # cannot slip into a remove/create gap.
+            os.replace(temporary, path)
+        else:
+            # Atomically publish a complete record without overwriting an old
+            # writer that may have created its legacy lock since our read.
+            os.link(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)