← Files ClaraARCHIVED FILE

modules/studio-archive/scripts/archive_core.py

278 KB · Nov 21, 2026 · 00:11 UTC

↓ Download file

See the change to this file →

"""Local, scope-bound studio archive indexing and retrieval."""

from __future__ import annotations

import atexit
import errno
import hashlib
import io
import json
import logging
import os
import re
import secrets
import shutil
import sqlite3
import stat

# Native folder selection uses fixed executable names and never invokes a shell.
import subprocess  # nosec B404
import sys
import tempfile
import warnings
import zipfile
from contextlib import contextmanager, nullcontext
from contextvars import ContextVar
from dataclasses import dataclass
from datetime import datetime, timezone
from email import policy
from email.parser import BytesParser
from email.utils import getaddresses
from functools import wraps
from html.parser import HTMLParser
from pathlib import Path, PurePosixPath
from threading import Lock, RLock
from typing import Any, Callable, Iterator, Mapping, Sequence


def _add_vera_assurance_module_path() -> None:
    """Load the packaged shared contract from source or an installed plugin."""

    candidates = (
        Path(__file__).resolve().parents[1] / "vendor" / "modules",
        Path(__file__).resolve().parents[2] / "_shared" / "vendor" / "modules",
    )
    for module_root in candidates:
        if (module_root / "vera_assurance").is_dir():
            if str(module_root) not in sys.path:
                sys.path.insert(0, str(module_root))
            return
    raise RuntimeError("The required vera_assurance module is not available.")


_add_vera_assurance_module_path()

_SCRIPT_DIRECTORY = Path(__file__).resolve().parent
if str(_SCRIPT_DIRECTORY) not in sys.path:
    sys.path.insert(0, str(_SCRIPT_DIRECTORY))

import archive_preferences as preferences  # noqa: E402
import client_ledger as ledger  # noqa: E402
import folder_intake  # noqa: E402
import google_drive as drive  # noqa: E402
import input_verification  # noqa: E402
from vera_assurance import (  # noqa: E402
    JOURNAL_SAMPLING_CHECK_ENTRIES_HANDOFF,
    VERA_CLIENT_WORKFLOW_IDS,
    build_studio_client_folder_binding,
)

CLIENT_WORKFLOW_IDS = (*VERA_CLIENT_WORKFLOW_IDS, "apertura-pratica")

__all__ = [
    "map_studio_legacy_incarichi",
    "read_studio_incarico_document",
    "begin_studio_incarico",
    "publish_studio_incarico_result",
    "reuse_studio_incarico_result",
    "get_studio_incarico",
    "update_studio_incarico",
    "ArchiveAccessError",
    "ArchiveError",
    "ArchiveFolderPickerUnavailableError",
    "ArchiveImportSourceError",
    "ArchiveNotConfiguredError",
    "SourceChangedError",
    "check_studio_import_sources",
    "cancel_studio_client_workflow",
    "checkpoint_studio_client_workflow",
    "restore_studio_client_workflow",
    "close_studio_client_engagement",
    "complete_studio_client_workflow",
    "configure_archive",
    "create_studio_client_engagement",
    "create_studio_client",
    "diagnose_archive_access",
    "fail_studio_client_workflow",
    "finalize_studio_client_workflow",
    "get_studio_client_folder",
    "get_studio_archive_organization_inventory",
    "authorize_studio_google_drive",
    "bind_studio_client_google_drive",
    "import_studio_client_document",
    "copy_studio_client_source_folder",
    "list_studio_client_engagements",
    "verify_studio_client_inputs",
    "list_studio_client_identities",
    "list_studio_clients",
    "normalize_studio_archive_layout",
    "match_studio_email_client",
    "open_archive_source",
    "open_studio_archive_organization_item",
    "open_studio_google_drive_source",
    "plan_gmail_client_search",
    "prepare_studio_client_workflow",
    "retain_studio_run_binding",
    "use_studio_run_context",
    "recover_studio_client_ledger",
    "refresh_archive",
    "report_studio_client_retention",
    "resolve_studio_client_identity",
    "search_archive",
    "setup_archive_with_folder_picker",
    "set_studio_client_identity",
    "snapshot_studio_client_folder",
    "snapshot_studio_client_google_drive",
    "start_check_entries_from_sample",
    "start_studio_client_workflow",
    "read_studio_run_artifact",
    "write_studio_run_artifact",
    "verify_studio_run_report",
    "studio_archive_status",
    "studio_google_drive_status",
]

SCHEMA_VERSION = "2"
CONFIG_SCHEMA_VERSION = 1
CLIENT_IDENTITIES_SCHEMA_VERSION = 2
STATE_ENV = "VERA_STUDIO_ARCHIVE_STATE_DIR"
CONFIG_FILENAME = "config.json"
SESSION_ENV = "VERA_STUDIO_ARCHIVE_SESSION_ID"
_PROCESS_SESSION = f"{os.getpid()}-{secrets.token_hex(16)}"
_STATE_LEASES: dict[Path, tuple[Any, bytes | None]] = {}
_STATE_BINDINGS: dict[Path, tuple[Any, Any]] = {}
_STATE_MUTEXES: dict[Path, Any] = {}
_STATE_DEPTH: dict[Path, int] = {}
_STATE_MUTEX_GUARD = Lock()
_CONFIGURATION_CHANGED = (
    "Studio Archive configuration changed during this run, "
    "re-validate before continuing."
)


def _session_id() -> str:
    """Share an identity across CLI commands only when the host supplies one."""
    return (
        os.environ.get(SESSION_ENV, "").strip()
        or os.environ.get("CODEX_THREAD_ID", "").strip()
        or _PROCESS_SESSION
    )


def _check_configuration(state: Path) -> None:
    """Reject changes to a configuration already observed by this process."""
    expected = _STATE_LEASES[state][1]
    path = state / CONFIG_FILENAME
    actual = path.read_bytes() if path.exists() else None
    if actual != expected:
        raise ArchiveError(_CONFIGURATION_CHANGED)


def _claim_state(state: Path) -> None:
    """Pin one operation; keep archive/session identity across later operations."""
    state = state.resolve()
    if state in _STATE_LEASES:
        _check_configuration(state)
        return
    state.mkdir(parents=True, exist_ok=True, mode=0o700)
    lease = preferences.file_lock(state / ".config.lock", label="configuration")
    try:
        lease.__enter__()
    except (OSError, ValueError) as exc:
        raise ArchiveError(f"Studio Archive configuration unavailable: {exc}") from exc
    path = state / CONFIG_FILENAME
    try:
        content = path.read_bytes() if path.exists() else None
        binding = _configuration_binding(content)
        if state in _STATE_BINDINGS and binding != _STATE_BINDINGS[state]:
            raise ArchiveError(_CONFIGURATION_CHANGED)
    except (OSError, ArchiveError):
        lease.__exit__(None, None, None)
        raise
    if content is not None:
        _STATE_BINDINGS[state] = binding
    _STATE_LEASES[state] = (lease, content)


def _configuration_binding(content: bytes | None) -> tuple[Any, Any]:
    """Scope changes may refresh between calls; archive and chat cannot switch."""
    if content is None:
        return None, None
    try:
        payload = json.loads(content)
    except (ValueError, UnicodeError) as exc:
        raise ArchiveError("Studio Archive configuration is unreadable.") from exc
    if not isinstance(payload, dict):
        raise ArchiveError("Studio Archive configuration is malformed.")
    return payload.get("archive_root"), payload.get("session_id")


def _release_state_lease(state: Path) -> None:
    lease = _STATE_LEASES.pop(state, None)
    if lease is not None:
        lease[0].__exit__(None, None, None)


def _release_state_leases() -> None:
    for state in tuple(_STATE_LEASES):
        _release_state_lease(state)
    _STATE_BINDINGS.clear()


atexit.register(_release_state_leases)
CLIENT_IDENTITIES_FILENAME = "client-identities.json"
GOOGLE_DRIVE_BINDINGS_FILENAME = "google-drive-bindings.json"
GOOGLE_DRIVE_AUTH_FILENAME = "google-drive-token.json"
GOOGLE_DRIVE_BINDINGS_SCHEMA = "vera.studio_archive_google_drive_bindings.v1"
ARCHIVE_ORGANIZATION_INVENTORY_SCHEMA = "vera.archive_organization_model_inventory.v1"
ARCHIVE_ORGANIZATION_INVENTORY_REF_PREFIX = "archive_inventory_"
ARCHIVE_ORGANIZATION_ITEM_REF_PREFIX = "archive_item_"
ARCHIVE_ORGANIZATION_DUPLICATE_REF_PREFIX = "exact_group_"
GOOGLE_DRIVE_EXPORTS = {
    "application/vnd.google-apps.document": ("text/plain", ".txt"),
    "application/vnd.google-apps.spreadsheet": (
        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        ".xlsx",
    ),
    "application/vnd.google-apps.presentation": ("application/pdf", ".pdf"),
    "application/vnd.google-apps.drawing": ("application/pdf", ".pdf"),
}
DATABASE_FILENAME = "archive.sqlite3"
MANAGED_ENGAGEMENTS_DIRECTORY = ledger.LEDGER_DIRECTORY

TEXT_SUFFIXES = {".txt", ".md", ".csv", ".json", ".xml"}
PDF_SUFFIXES = {".pdf"}
DOCX_SUFFIXES = {".docx"}
XLSX_SUFFIXES = {".xlsx"}
EMAIL_SUFFIXES = {".eml"}
IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".tif", ".tiff"}
SUPPORTED_SUFFIXES = (
    TEXT_SUFFIXES
    | PDF_SUFFIXES
    | DOCX_SUFFIXES
    | XLSX_SUFFIXES
    | EMAIL_SUFFIXES
    | IMAGE_SUFFIXES
)

MAX_FILES = 50_000
MAX_TOTAL_BYTES = 50 * 1024 * 1024 * 1024
MAX_FILE_BYTES = 256 * 1024 * 1024
MAX_TEXT_BYTES = 20 * 1024 * 1024
MAX_EMAIL_BYTES = 30 * 1024 * 1024
MAX_PDF_BYTES = 100 * 1024 * 1024
MAX_PDF_PAGES = 500
MAX_PDF_TEXT_CHARS = 20_000_000
MAX_IMAGE_FRAMES = 100
MAX_IMAGE_TOTAL_PIXELS = 20_000_000
MAX_WORKBOOK_SHEETS = 100
MAX_WORKSHEET_ROWS = 20_000
MAX_WORKSHEET_COLUMNS = 512
MAX_OOXML_MEMBER_BYTES = 20 * 1024 * 1024
MAX_OOXML_TOTAL_BYTES = 100 * 1024 * 1024
MAX_OOXML_MEMBERS = 5_000
MAX_OOXML_COMPRESSION_RATIO = 200
MAX_CHUNK_CHARS = 6_000
MAX_CHUNK_LINES = 120
MAX_SEARCH_TOKENS = 24
MAX_OPEN_CHARS = 24_000
MAX_STATUS_SCAN_ISSUES = 200
MAX_STATUS_DOCUMENT_ISSUES = 200
MAX_CLIENT_IDENTITIES = 5_000
MAX_CLIENT_EMAIL_ADDRESSES = 20
MAX_CLIENT_LEGAL_NAMES = 20
MAX_CLIENT_TAX_IDENTIFIERS = 20
MAX_GMAIL_QUERY_IDENTITIES = 10
MAX_GMAIL_TOPIC_CHARS = 200
SUPPORTED_ENGAGEMENT_IMPORT_ROLES = {"journal", "source", "support"}
IGNORED_NAMES = {
    ".DS_Store",
    ".git",
    ".hg",
    ".svn",
    "Thumbs.db",
    "__pycache__",
    "desktop.ini",
}

ARCHIVE_HOST_PERMISSION_REQUIRED = "MPARANZA_ARCHIVE_HOST_PERMISSION_REQUIRED"
_SMB_CREDENTIAL_WINERRORS = frozenset({86, 1219, 1326, 1909})
_NETWORK_UNAVAILABLE_WINERRORS = frozenset({53, 64, 67, 121, 1231, 1232})
_ACCESS_DENIED_WINERRORS = frozenset({5})
_ACCESS_DENIED_ERRNOS = frozenset({errno.EACCES, errno.EPERM})


class ArchiveError(RuntimeError):
    """Base class for bounded archive workflow errors."""

    code = "archive_error"

    def __init__(
        self, *args: object, technical_facts: dict[str, int | bool] | None = None
    ) -> None:
        super().__init__(*args)
        self.incident_technical_facts = technical_facts or {}


class ArchiveImportSourceError(ArchiveError):
    """Keep a failed import's recovery information and existing identifiers."""

    def __init__(self, result: Mapping[str, Any], **identity: str) -> None:
        super().__init__(str(result["message"]))
        self.code = str(result["code"])
        self.details = {
            **result,
            **identity,
            "resume_existing_engagement": bool(identity.get("engagement_id")),
            "direct_chat_attachment_import_supported": False,
        }


class ArchiveAccessError(ArchiveError):
    """Describe one mechanically observed archive-root access failure safely."""

    def __init__(
        self,
        message: str,
        *,
        code: str,
        stage: str,
        path_kind: str,
        recommended_action: str,
        host_access_approved: bool,
        error: OSError | None = None,
    ) -> None:
        super().__init__(message)
        self.code = code
        details: dict[str, Any] = {
            "category": code,
            "stage": stage,
            "path_kind": path_kind,
            "recommended_action": recommended_action,
            "host_access_approved": host_access_approved,
        }
        if error is not None:
            if isinstance(error.errno, int):
                details["errno"] = error.errno
            winerror = getattr(error, "winerror", None)
            if isinstance(winerror, int):
                details["winerror"] = winerror
        self.details = details


class ArchiveNotConfiguredError(ArchiveError):
    """Raised when an operation needs a configured archive."""

    code = "archive_not_configured"

    def __init__(self, message: str) -> None:
        super().__init__(message)
        self.details = _studio_archive_setup_contract()


class ArchiveFolderPickerUnavailableError(ArchiveError):
    """Raised when this desktop runtime cannot open a native folder picker."""

    code = "archive_folder_picker_unavailable"

    def __init__(self) -> None:
        super().__init__(
            "The native Studio Archive folder chooser is unavailable on this runtime."
        )
        self.details = {
            **_studio_archive_setup_contract(),
            "manual_path_fallback_allowed": True,
        }


class SourceChangedError(ArchiveError):
    """Raised when an indexed source no longer matches its recorded bytes."""

    code = "source_changed_refresh_required"


@dataclass(frozen=True)
class Scope:
    """One mechanically selected archive-relative search boundary."""

    scope_id: str
    relative_dir: str
    display_name: str

    def as_json(self) -> dict[str, str]:
        """Return a JSON-safe scope record."""

        return {
            "scope_id": self.scope_id,
            "relative_dir": self.relative_dir,
            "display_name": self.display_name,
        }


@dataclass(frozen=True)
class ArchiveConfig:
    """One user's local archive configuration."""

    archive_root: Path
    scopes: tuple[Scope, ...]
    configured_at: str
    scope_issues: tuple[dict[str, Any], ...] = ()
    directory_issue: dict[str, Any] | None = None

    def as_json(self) -> dict[str, Any]:
        """Return the persisted configuration shape."""

        return {
            "schema_version": CONFIG_SCHEMA_VERSION,
            "archive_root": str(self.archive_root),
            "configured_at": self.configured_at,
            "scopes": [scope.as_json() for scope in self.scopes],
        }


@dataclass(frozen=True)
class ClientIdentity:
    """One private client identity record bound to an exact archive scope."""

    client_id: str
    scope_id: str
    email_addresses: tuple[str, ...]
    legal_names: tuple[str, ...]
    tax_identifiers: tuple[str, ...]
    updated_at: str

    def as_json(self) -> dict[str, Any]:
        """Return the persisted private-registry shape."""

        return {
            "client_id": self.client_id,
            "scope_id": self.scope_id,
            "email_addresses": list(self.email_addresses),
            "legal_names": list(self.legal_names),
            "tax_identifiers": list(self.tax_identifiers),
            "updated_at": self.updated_at,
        }


@dataclass(frozen=True)
class DiscoveredFile:
    """One regular source file discovered inside a configured scope."""

    scope_id: str
    relative_path: str
    path: Path
    size_bytes: int
    mtime_ns: int


@dataclass(frozen=True)
class ScanIssue:
    """One skipped archive entry that may limit search completeness."""

    scope_id: str
    relative_path: str
    reason: str
    size_bytes: int | None

    def as_json(self) -> dict[str, Any]:
        """Return a JSON-safe scan issue."""

        return {
            "scope_id": self.scope_id,
            "relative_path": self.relative_path,
            "reason": self.reason,
            "size_bytes": self.size_bytes,
        }


@dataclass(frozen=True)
class ExtractedChunk:
    """One bounded, citable source fragment."""

    ordinal: int
    locator_kind: str
    locator_value: str
    text: str


@dataclass(frozen=True)
class ExtractionResult:
    """Mechanically extracted chunks and limitations for one source."""

    chunks: tuple[ExtractedChunk, ...]
    extraction_method: str
    status: str
    needs_ocr: bool
    limitations: tuple[str, ...]


class _HtmlTextExtractor(HTMLParser):
    """Collect visible text from an HTML email part."""

    def __init__(self) -> None:
        super().__init__()
        self.parts: list[str] = []

    def handle_data(self, data: str) -> None:
        """Keep non-empty visible text."""

        if data.strip():
            self.parts.append(data)


def _now_iso() -> str:
    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()


def _sha256_bytes(payload: bytes) -> str:
    return hashlib.sha256(payload).hexdigest()


def _sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    flags = os.O_RDONLY
    if hasattr(os, "O_NOFOLLOW"):
        flags |= os.O_NOFOLLOW
    descriptor = os.open(path, flags)
    with os.fdopen(descriptor, "rb") as handle:
        if not stat.S_ISREG(os.fstat(handle.fileno()).st_mode):
            raise ArchiveError("Studio Archive source is not a regular file.")
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def _stable_id(prefix: str, *values: str) -> str:
    payload = "\x1f".join(values).encode("utf-8")
    return f"{prefix}_{hashlib.sha256(payload).hexdigest()[:24]}"


def _new_private_id(prefix: str, existing: set[str]) -> str:
    """Create an opaque persistent ID; identity must not depend on a folder name."""

    for _ in range(100):
        candidate = f"{prefix}_{secrets.token_hex(12)}"
        if candidate not in existing:
            return candidate
    raise ArchiveError(f"Could not allocate a unique {prefix} identifier.")


def _state_location(explicit: Path | None = None) -> Path:
    """Locate state without requiring optional Archive storage to be available."""
    selected = explicit
    if selected is None:
        environment_value = os.environ.get(STATE_ENV, "").strip()
        selected = (
            Path(environment_value).expanduser()
            if environment_value
            else preferences.default_state_directory()
            / "sessions"
            / hashlib.sha256(_session_id().encode("utf-8")).hexdigest()[:32]
        )
    selected = Path(selected).expanduser()
    if not selected.is_absolute():
        raise ArchiveError("Studio Archive state directory must be absolute.")
    if selected.is_symlink():
        raise ArchiveError("Studio Archive state directory cannot be a symbolic link.")
    return selected.resolve()


def _state_dir(
    explicit: Path | None = None,
    *,
    create: bool = False,
) -> Path:
    selected = _state_location(explicit)
    selection_explicit = explicit is not None
    selection_environment = not selection_explicit and bool(
        os.environ.get(STATE_ENV, "").strip()
    )
    if create:
        selected.mkdir(parents=True, exist_ok=True, mode=0o700)
        try:
            if os.name == "posix" and stat.S_IMODE(selected.stat().st_mode) != 0o700:
                selected.chmod(0o700)
        except OSError as exc:
            raise ArchiveError(f"Could not secure Studio Archive state: {exc}") from exc
    elif selected.exists() and not selected.is_dir():
        raise ArchiveError("Studio Archive state path must be a directory.")
    elif (
        selected.exists()
        and os.name == "posix"
        and stat.S_IMODE(selected.stat().st_mode) & 0o077
    ):
        observed = selected.stat()
        facts = {
            "archive_state.mode": stat.S_IMODE(observed.st_mode),
            "archive_state.private_creation_mode": 0o700,
            "archive_state.forbidden_mode_bits": 0o077,
            "archive_state.owner_uid": observed.st_uid,
            "archive_state.process_euid": os.geteuid(),
            "archive_state.owner_matches_process": observed.st_uid == os.geteuid(),
            "archive_state.owner_gid": observed.st_gid,
            "archive_state.process_egid": os.getegid(),
            "archive_state.is_directory": stat.S_ISDIR(observed.st_mode),
            "archive_state.is_symlink": selected.is_symlink(),
            "archive_state.selection_explicit": selection_explicit,
            "archive_state.selection_environment": selection_environment,
            "archive_state.selection_default": not (
                selection_explicit or selection_environment
            ),
            "archive_state.create_requested": create,
        }
        raise ArchiveError(
            "Studio Archive state directory must not be accessible by group or others.",
            technical_facts=facts,
        )
    return selected.resolve()


def _config_path(state_dir: Path) -> Path:
    return state_dir / CONFIG_FILENAME


def _archive_profile(state_dir: Path) -> Path | None:
    """Keep approved root discovery private and independent of session leases."""
    try:
        return preferences.profile_directory(state_dir)
    except (OSError, ValueError) as exc:
        raise ArchiveError(f"Archive profile unavailable: {exc}") from exc


def _profile_registry_directory(state_dir: Path) -> Path | None:
    if _archive_profile(state_dir) is None:
        return None
    config = _load_config(state_dir, validate_scope_roots=False)
    return _profile_directory_for_root(state_dir, config.archive_root)


def _profile_directory_for_root(state_dir: Path, root: Path) -> Path | None:
    """Keep private discovery records outside every selected source tree."""
    profile = _archive_profile(state_dir)
    if profile is None:
        return None
    if _path_is_within(profile, root) or _path_is_within(root, profile):
        raise ArchiveError(
            "Private archive profile must be outside the source archive."
        )
    key = hashlib.sha256(str(root).encode()).hexdigest()
    return profile / "archives" / key


def _client_identities_path(state_dir: Path) -> Path:
    directory = _profile_registry_directory(state_dir)
    return (directory or state_dir) / CLIENT_IDENTITIES_FILENAME


def _identity_transaction(function: Callable[..., Any]) -> Callable[..., Any]:
    """Lock the exact root's shared aliases across the whole identity transaction."""

    @wraps(function)
    def wrapped(*args: Any, **kwargs: Any) -> Any:
        state = _state_dir(
            kwargs.get(
                "state_dir", args[0] if args and isinstance(args[0], Path) else None
            )
        )
        profile = _archive_profile(state)
        config = (
            _load_config(state, validate_scope_roots=False)
            if profile is not None
            else None
        )
        try:
            if profile is not None and config is not None:
                if _path_is_within(profile, config.archive_root) or _path_is_within(
                    config.archive_root, profile
                ):
                    raise ArchiveError(
                        "Private archive profile must be outside the source archive."
                    )
            guard = (
                preferences.registry_lock(profile, config.archive_root)
                if profile is not None and config is not None
                else nullcontext()
            )
            with guard:
                shared = _client_identities_path(state)
                legacy = state / CLIENT_IDENTITIES_FILENAME
                if shared != legacy and not shared.exists() and legacy.is_file():
                    # Migrate only this approved session, never scan another session.
                    _assert_private_file(legacy, "client identity registry")
                    records = _load_client_identity_file(legacy)
                    _write_private_json(
                        shared,
                        {
                            "schema_version": CLIENT_IDENTITIES_SCHEMA_VERSION,
                            "clients": [record.as_json() for record in records],
                        },
                    )
                return function(*args, **kwargs)
        except (OSError, ValueError) as exc:
            raise ArchiveError(
                f"Archive identity transaction unavailable: {exc}"
            ) from exc

    return wrapped


def _remember_approved_root(state: Path, root: Path) -> None:
    profile = _archive_profile(state)
    if profile is None:
        return
    if _path_is_within(profile, root) or _path_is_within(root, profile):
        raise ArchiveError(
            "Private archive profile must be outside the source archive."
        )
    profile.mkdir(parents=True, exist_ok=True, mode=0o700)
    if os.name == "posix" and stat.S_IMODE(profile.stat().st_mode) != 0o700:
        profile.chmod(0o700)
    path = profile / "approved-archive.json"
    payload = {"schema_version": 2, "archive_root": str(root)}
    with preferences.file_lock(
        profile / ".approved-archive.lock", label="default archive"
    ):
        if preferences.read_json(path) != payload:
            _write_private_json(path, payload)


def _restore_approved_root(state: Path) -> None:
    if _config_path(state).exists():
        return
    profile = _archive_profile(state)
    if profile is None:
        return
    try:
        saved = preferences.read_json(profile / "approved-archive.json")
    except (OSError, ValueError) as exc:
        raise ArchiveError(f"Approved archive preference is unreadable: {exc}") from exc
    if saved is None:
        return
    if (
        set(saved) != {"schema_version", "archive_root"}
        or saved["schema_version"] not in {1, 2}
        or not isinstance(saved["archive_root"], str)
    ):
        raise ArchiveError("Approved archive preference is malformed.")
    if saved["schema_version"] == 1:
        # Older versions also saved temporary roots here. Require a studio choice.
        return
    # Revalidate access and derive fresh scopes; never copy an old session config.
    configure_archive(Path(saved["archive_root"]), state_dir=state)


def _remember_known_scopes(state: Path, config: ArchiveConfig) -> dict[str, str]:
    """Cache a complete observed directory without making cache writes a prerequisite."""
    if config.directory_issue is not None or config.scope_issues:
        return {"status": "retained", "reason": "current_discovery_incomplete"}
    try:
        directory = _profile_directory_for_root(state, config.archive_root)
        if directory is None:
            return {"status": "not_configured"}
        path = directory / "known-scopes.json"
        payload = {
            "schema_version": 1,
            "archive_root": str(config.archive_root),
            "scopes": [scope.as_json() for scope in config.scopes],
        }
        if preferences.read_json(path) == payload:
            return {"status": "current"}
        # This derived cache can wait; an active alias transaction must not
        # delay client work merely to refresh folder-location hints.
        with preferences.registry_lock(
            directory.parents[1], config.archive_root, timeout_seconds=0
        ):
            if preferences.read_json(path) != payload:
                _write_private_json(path, payload)
        return {"status": "saved"}
    except (ArchiveError, OSError, ValueError) as exc:
        logging.getLogger(__name__).warning(
            "Archive folder cache remains unavailable: %s", type(exc).__name__
        )
        return {"status": "unavailable", "reason": type(exc).__name__}


def _known_scopes(state: Path, root: Path) -> tuple[Scope, ...]:
    """Read exact previously observed locations; selected identities still need validation."""
    directory = _profile_directory_for_root(state, root)
    if directory is None:
        return ()
    payload = preferences.read_json(directory / "known-scopes.json")
    if payload is None:
        return ()
    if (
        set(payload) != {"schema_version", "archive_root", "scopes"}
        or payload["schema_version"] != 1
        or payload["archive_root"] != str(root)
        or not isinstance(payload["scopes"], list)
        or not 1 <= len(payload["scopes"]) <= MAX_CLIENT_IDENTITIES + 1
    ):
        raise ArchiveError("Saved archive folder locations are invalid.")
    scopes = []
    for item in payload["scopes"]:
        if not isinstance(item, dict) or not isinstance(item.get("relative_dir"), str):
            raise ArchiveError("Saved archive folder location is invalid.")
        relative = item["relative_dir"]
        if relative != "." and (
            relative in {"", ".."}
            or Path(relative).name != relative
            or "\\" in relative
        ):
            raise ArchiveError(
                "Saved archive folder location is not an immediate child."
            )
        scope = _scope_from_relative(relative, root)
        if scope.as_json() != item:
            raise ArchiveError(
                "Saved archive folder location does not match its identity."
            )
        scopes.append(scope)
    if len({scope.scope_id for scope in scopes}) != len(scopes):
        raise ArchiveError("Saved archive folder locations are ambiguous.")
    return tuple(scopes)


def _google_drive_bindings_path(state_dir: Path) -> Path:
    return state_dir / GOOGLE_DRIVE_BINDINGS_FILENAME


def _google_drive_token_path(state_dir: Path) -> Path:
    return state_dir / GOOGLE_DRIVE_AUTH_FILENAME


def _database_path(state_dir: Path) -> Path:
    """Reuse the owner-private index for this exact archive across chats."""
    config = _load_config(state_dir, validate_scope_roots=False)
    directory = _profile_directory_for_root(state_dir, config.archive_root)
    if directory is None:
        return state_dir / DATABASE_FILENAME
    import archive_search_cache

    return archive_search_cache.database_path(
        directory, state_dir, config.archive_root, SCHEMA_VERSION
    )


def _assert_private_file(path: Path, label: str) -> None:
    if os.name != "posix" or not path.exists():
        return
    if stat.S_IMODE(path.stat().st_mode) & 0o077:
        raise ArchiveError(
            f"Studio Archive {label} must not be accessible by group or others."
        )


def _write_private_json(path: Path, payload: dict[str, Any]) -> None:
    if path.name == CONFIG_FILENAME:
        _claim_state(path.parent)
        existing = _STATE_LEASES[path.parent.resolve()][1]
        if existing is not None:
            owner = json.loads(existing).get("session_id")
            if owner is not None and owner != _session_id():
                raise ArchiveError(_CONFIGURATION_CHANGED)
        payload = {**payload, "session_id": _session_id()}
    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
    descriptor, temporary_name = tempfile.mkstemp(
        prefix=f".{path.name}.",
        suffix=".tmp",
        dir=path.parent,
    )
    temporary = Path(temporary_name)
    try:
        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
            json.dump(payload, handle, ensure_ascii=False, indent=2, sort_keys=True)
            handle.write("\n")
            handle.flush()
            os.fsync(handle.fileno())
        if os.name == "posix" and stat.S_IMODE(temporary.stat().st_mode) != 0o600:
            temporary.chmod(0o600)
        written_bytes = temporary.read_bytes() if path.name == CONFIG_FILENAME else None
        temporary.replace(path)
        if path.name == CONFIG_FILENAME:
            state = path.parent.resolve()
            _STATE_LEASES[state] = (_STATE_LEASES[state][0], written_bytes)
            _STATE_BINDINGS[state] = _configuration_binding(written_bytes)
    finally:
        if temporary.exists():
            temporary.unlink()


def _path_is_within(path: Path, parent: Path) -> bool:
    try:
        path.relative_to(parent)
    except ValueError:
        return False
    return True


def _archive_path_kind(path: Path) -> str:
    """Classify only path syntax needed for access diagnostics."""

    raw_path = os.fspath(path)
    if raw_path.startswith(("\\\\", "//")):
        return "unc_share"
    return "local_or_mounted"


def _archive_access_error(
    error: OSError,
    *,
    stage: str,
    path_kind: str,
    host_access_approved: bool,
) -> ArchiveAccessError:
    """Map stable OS error codes to auditable access categories.

    Fixed codes are appropriate here because they are mechanically emitted by
    the operating system. Unknown combinations remain unclassified instead of
    inferring a credential, sandbox, or filesystem-permission cause.
    """

    winerror = getattr(error, "winerror", None)
    if winerror in _SMB_CREDENTIAL_WINERRORS:
        return ArchiveAccessError(
            "The operating system rejected the SMB session or credentials for the "
            "selected network share. Connect the share in the signed-in desktop "
            "session and retry; Vera never requests or stores SMB credentials.",
            code="archive_smb_credentials_required",
            stage=stage,
            path_kind=path_kind,
            recommended_action="connect_smb_session",
            host_access_approved=host_access_approved,
            error=error,
        )
    if winerror in _NETWORK_UNAVAILABLE_WINERRORS:
        return ArchiveAccessError(
            "The selected network share is unreachable from this desktop session. "
            "Verify the server and share connection, then retry the same path.",
            code="archive_network_share_unreachable",
            stage=stage,
            path_kind=path_kind,
            recommended_action="verify_share_connection",
            host_access_approved=host_access_approved,
            error=error,
        )
    access_denied = (
        error.errno in _ACCESS_DENIED_ERRNOS or winerror in _ACCESS_DENIED_WINERRORS
    )
    if access_denied and os.environ.get("CODEX_SANDBOX") and not host_access_approved:
        return ArchiveAccessError(
            f"{ARCHIVE_HOST_PERMISSION_REQUIRED}: Codex could not read the selected "
            "archive root from its current sandbox. Retry the same access diagnostic "
            "with host folder access approval before creating a client or engagement.",
            code="archive_host_access_permission_required",
            stage=stage,
            path_kind=path_kind,
            recommended_action="retry_with_host_folder_access",
            host_access_approved=False,
            error=error,
        )
    if access_denied:
        return ArchiveAccessError(
            "The operating system denied filesystem access to the selected archive "
            "root. Grant the signed-in user share and filesystem read/list permissions "
            "and write permission before client registration, then retry.",
            code="archive_filesystem_access_denied",
            stage=stage,
            path_kind=path_kind,
            recommended_action="grant_share_and_filesystem_permissions",
            host_access_approved=host_access_approved,
            error=error,
        )
    if error.errno == errno.ENOENT:
        return ArchiveAccessError(
            "The selected archive root does not exist in this desktop session.",
            code="archive_root_not_found",
            stage=stage,
            path_kind=path_kind,
            recommended_action="verify_archive_root",
            host_access_approved=host_access_approved,
            error=error,
        )
    return ArchiveAccessError(
        "The selected archive root is unavailable for an unclassified operating-system "
        "reason. The diagnostic has preserved the numeric error code without exposing "
        "the private path.",
        code="archive_root_unavailable",
        stage=stage,
        path_kind=path_kind,
        recommended_action="review_os_error_code",
        host_access_approved=host_access_approved,
        error=error,
    )


def _validate_archive_root(
    root: Path,
    state_dir: Path,
    *,
    host_access_approved: bool = False,
) -> Path:
    candidate = Path(root).expanduser()
    path_kind = _archive_path_kind(candidate)
    if not candidate.is_absolute():
        if path_kind == "unc_share":
            raise ArchiveAccessError(
                "UNC syntax is not a local absolute path on this runtime. Mount the "
                "share as a local drive or folder and provide that mounted absolute "
                "path; Vera never requests SMB credentials.",
                code="archive_unc_requires_local_mount",
                stage="path_validation",
                path_kind=path_kind,
                recommended_action="mount_share_locally",
                host_access_approved=host_access_approved,
            )
        raise ArchiveError("Archive root must be an absolute path.")
    if candidate.is_symlink():
        raise ArchiveError("Archive root cannot be a symbolic link.")
    try:
        resolved = candidate.resolve(strict=True)
    except OSError as exc:
        raise _archive_access_error(
            exc,
            stage="path_resolution",
            path_kind=path_kind,
            host_access_approved=host_access_approved,
        ) from exc
    try:
        resolved_mode = resolved.stat().st_mode
    except OSError as exc:
        raise _archive_access_error(
            exc,
            stage="root_metadata",
            path_kind=path_kind,
            host_access_approved=host_access_approved,
        ) from exc
    if not stat.S_ISDIR(resolved_mode):
        raise ArchiveError("Archive root must be a directory.")
    if _path_is_within(state_dir, resolved) or _path_is_within(resolved, state_dir):
        raise ArchiveError(
            "The private Studio Archive state directory and source archive must "
            "not contain one another."
        )
    return resolved


def _scope_from_relative(relative_dir: str, root: Path) -> Scope:
    if relative_dir == ".":
        display_name = root.name or "Studio Archive"
    else:
        display_name = Path(relative_dir).name
    return Scope(
        scope_id=_stable_id("scope", relative_dir.casefold()),
        relative_dir=relative_dir,
        display_name=display_name,
    )


def _discover_top_level_scopes(
    root: Path,
    *,
    host_access_approved: bool = False,
    issues: list[dict[str, Any]] | None = None,
) -> tuple[Scope, ...]:
    directories: list[Path] = []
    root_files = 0
    path_kind = _archive_path_kind(root)
    try:
        entries = sorted(root.iterdir(), key=lambda path: path.name.casefold())
    except OSError as exc:
        raise _archive_access_error(
            exc,
            stage="root_listing",
            path_kind=path_kind,
            host_access_approved=host_access_approved,
        ) from exc
    for path in entries:
        if path.name in IGNORED_NAMES:
            continue
        try:
            mode = path.lstat().st_mode
        except OSError as exc:
            if issues is None:
                raise _archive_access_error(
                    exc,
                    stage="root_entry_metadata",
                    path_kind=path_kind,
                    host_access_approved=host_access_approved,
                ) from exc
            # Keep the unavailable name visible without asserting it is usable
            # or preventing inspection of independent customer folders.
            directories.append(path)
            issues.append(
                {
                    **_scope_from_relative(path.name, root).as_json(),
                    "issue_code": "scope_metadata_unavailable",
                    "reason": "Folder metadata is unavailable; original records are preserved.",
                    "error_type": type(exc).__name__,
                    "available": False,
                }
            )
            continue
        if stat.S_ISLNK(mode):
            root_files += 1
        elif stat.S_ISDIR(mode):
            directories.append(path)
        elif stat.S_ISREG(mode):
            root_files += 1
    if directories:
        directory_scopes = tuple(
            _scope_from_relative(path.relative_to(root).as_posix(), root)
            for path in directories
        )
        scopes = (
            (*directory_scopes, _scope_from_relative(".", root))
            if root_files
            else directory_scopes
        )
        if len({scope.scope_id for scope in scopes}) != len(scopes):
            if issues is None:
                raise ArchiveError(
                    "Top-level archive directory names collide when case is ignored."
                )
            by_id: dict[str, list[Scope]] = {}
            for scope in scopes:
                by_id.setdefault(scope.scope_id, []).append(scope)
            for group in by_id.values():
                if len(group) > 1:
                    issues.append(
                        {
                            **group[0].as_json(),
                            "relative_dirs": [item.relative_dir for item in group],
                            "issue_code": "scope_name_collision",
                            "reason": "These folder names share a case-insensitive scope identity.",
                            "available": False,
                        }
                    )
            scopes = tuple(group[0] for group in by_id.values())
        return scopes
    if root_files:
        return (_scope_from_relative(".", root),)
    return (_scope_from_relative(".", root),)


def _config_matches(
    path: Path,
    *,
    archive_root: Path,
    scopes: tuple[Scope, ...],
) -> bool:
    """Compare a persisted config without requiring its old paths to exist."""

    try:
        payload = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError):
        return False
    return (
        payload.get("schema_version") == CONFIG_SCHEMA_VERSION
        and payload.get("archive_root") == str(archive_root)
        and payload.get("scopes") == [scope.as_json() for scope in scopes]
    )


def configure_archive(
    archive_root: Path,
    *,
    state_dir: Path | None = None,
    host_access_approved: bool = False,
    make_studio_default: bool = False,
) -> dict[str, Any]:
    """Configure one local archive and mechanically discover its top-level scopes."""

    planned_state = _state_dir(state_dir)
    root = _validate_archive_root(
        archive_root,
        planned_state,
        host_access_approved=host_access_approved,
    )
    profile = _archive_profile(planned_state)
    if profile is not None and (
        _path_is_within(profile, root) or _path_is_within(root, profile)
    ):
        raise ArchiveError(
            "Private archive profile must be outside the source archive."
        )
    private_state = _state_dir(state_dir, create=True)
    scope_issues: list[dict[str, Any]] = []
    directory_issue = None
    try:
        scopes = _discover_top_level_scopes(
            root, host_access_approved=host_access_approved, issues=scope_issues
        )
    except ArchiveAccessError as exc:
        if exc.details["stage"] != "root_listing":
            raise
        scopes = _known_scopes(private_state, root)
        if not scopes:
            raise
        directory_issue = {
            "issue_code": "scope_listing_unavailable",
            "reason": str(exc),
            "available": False,
            "known_scopes_only": True,
        }
    _claim_state(private_state)
    config_path = _config_path(private_state)
    if config_path.is_file() and _config_matches(
        config_path,
        archive_root=root,
        scopes=scopes,
    ):
        if os.name == "posix" and stat.S_IMODE(config_path.stat().st_mode) != 0o600:
            config_path.chmod(0o600)
        if make_studio_default:
            _remember_approved_root(private_state, root)
        status = studio_archive_status(state_dir=private_state)
        status["scope_cache"] = _remember_known_scopes(
            private_state,
            ArchiveConfig(root, scopes, "", tuple(scope_issues), directory_issue),
        )
        return status
    config = ArchiveConfig(
        archive_root=root,
        scopes=scopes,
        configured_at=_now_iso(),
        scope_issues=tuple(scope_issues),
        directory_issue=directory_issue,
    )
    _write_private_json(config_path, config.as_json())
    if make_studio_default:
        _remember_approved_root(private_state, root)
    scope_cache = _remember_known_scopes(private_state, config)
    status = studio_archive_status(state_dir=private_state)
    status["scope_cache"] = scope_cache
    return status


def _studio_archive_setup_contract() -> dict[str, Any]:
    """Describe the fixed local recovery path for first-time configuration."""

    return {
        "setup_required": True,
        "guided_setup": {
            "tool_name": "setup_studio_archive",
            "action": "select_folder_and_configure",
            "selection_mode": "native_directory_picker",
        },
        "manual_path_fallback": {
            "diagnose_tool_name": "diagnose_studio_archive_access",
            "configure_tool_name": "configure_studio_archive",
            "allowed_after": "archive_folder_picker_unavailable",
        },
    }


def _native_folder_picker_command() -> tuple[str, ...]:
    """Build fixed argv for the mechanically known desktop platform.

    Platform selection is deterministic because it enforces a local, no-shell
    UI boundary; it does not interpret the user's archive or client semantics.
    """

    if sys.platform == "darwin":
        executable = shutil.which("osascript")
        if executable is None:
            raise ArchiveFolderPickerUnavailableError()
        script = (
            'try\nPOSIX path of (choose folder with prompt "Select the Vera Studio '
            'Archive folder")\non error number -128\nreturn ""\nend try'
        )
        return (executable, "-e", script)
    if sys.platform == "win32":
        executable = (
            shutil.which("powershell.exe")
            or shutil.which("powershell")
            or shutil.which("pwsh")
        )
        if executable is None:
            raise ArchiveFolderPickerUnavailableError()
        script = (
            "[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); "
            "Add-Type -AssemblyName System.Windows.Forms; "
            "$dialog = New-Object System.Windows.Forms.FolderBrowserDialog; "
            "$dialog.Description = 'Select the Vera Studio Archive folder'; "
            "$dialog.ShowNewFolderButton = $false; "
            "if ($dialog.ShowDialog() -eq "
            "[System.Windows.Forms.DialogResult]::OK) { "
            "[Console]::Out.Write($dialog.SelectedPath) }"
        )
        return (executable, "-NoProfile", "-STA", "-Command", script)
    for executable_name, arguments in (
        (
            "zenity",
            (
                "--file-selection",
                "--directory",
                "--title=Select the Vera Studio Archive folder",
            ),
        ),
        (
            "kdialog",
            (
                "--getexistingdirectory",
                ".",
                "--title",
                "Select the Vera Studio Archive folder",
            ),
        ),
    ):
        executable = shutil.which(executable_name)
        if executable is not None:
            return (executable, *arguments)
    raise ArchiveFolderPickerUnavailableError()


def _select_archive_root_with_native_picker() -> Path | None:
    """Return the directory selected by the user, or ``None`` after cancellation."""

    command = _native_folder_picker_command()
    try:
        # The command is fixed per supported platform; selected paths are output only.
        completed = subprocess.run(  # nosec B603
            command,
            capture_output=True,
            text=True,
            check=False,
            timeout=300,
            encoding="utf-8",
        )
    except (OSError, subprocess.TimeoutExpired) as exc:
        raise ArchiveFolderPickerUnavailableError() from exc
    selected = completed.stdout.strip()
    if completed.returncode == 0:
        return Path(selected) if selected else None
    if completed.returncode == 1 and not completed.stderr.strip():
        return None
    raise ArchiveFolderPickerUnavailableError()


def setup_archive_with_folder_picker(
    *,
    state_dir: Path | None = None,
    folder_selector: Callable[[], Path | None] | None = None,
) -> dict[str, Any]:
    """Select, diagnose, and configure one archive root through a local picker."""

    selector = folder_selector or _select_archive_root_with_native_picker
    selected_root = selector()
    if selected_root is None:
        return {
            "configured": False,
            "setup_status": "cancelled",
            **_studio_archive_setup_contract(),
        }
    diagnostic = diagnose_archive_access(selected_root, state_dir=state_dir)
    result = configure_archive(
        selected_root, state_dir=state_dir, make_studio_default=True
    )
    result.pop("archive_root", None)
    result.update(
        {
            "setup_status": "configured",
            "setup_required": False,
            "archive_root_returned": False,
            "access_diagnostic": diagnostic,
        }
    )
    return result


def diagnose_archive_access(
    archive_root: Path,
    *,
    state_dir: Path | None = None,
    host_access_approved: bool = False,
) -> dict[str, Any]:
    """Verify archive-root path resolution and listing without persisting state."""

    planned_state = _state_dir(state_dir)
    root = _validate_archive_root(
        archive_root,
        planned_state,
        host_access_approved=host_access_approved,
    )
    scopes = _discover_top_level_scopes(
        root,
        host_access_approved=host_access_approved,
    )
    return {
        "ok": True,
        "path_kind": _archive_path_kind(root),
        "path_resolution": "available",
        "root_listing": "readable",
        "scope_count": len(scopes),
        "host_access_approved": host_access_approved,
        "client_ledger_write_access": "not_tested",
        "private_path_returned": False,
    }


def _load_config(
    state_dir: Path,
    *,
    validate_scope_roots: bool = True,
) -> ArchiveConfig:
    _restore_approved_root(state_dir)
    _claim_state(state_dir)
    path = _config_path(state_dir)
    if not path.is_file():
        raise ArchiveNotConfiguredError(
            "Studio Archive is not configured. Start the guided folder setup first."
        )
    _assert_private_file(path, "configuration")
    try:
        payload = json.loads(_STATE_LEASES[state_dir.resolve()][1] or b"null")
    except (OSError, json.JSONDecodeError) as exc:
        raise ArchiveError(
            f"Studio Archive configuration is unreadable: {exc}"
        ) from exc
    if payload.get("session_id", _session_id()) != _session_id():
        raise ArchiveError(_CONFIGURATION_CHANGED)
    if payload.get("schema_version") != CONFIG_SCHEMA_VERSION:
        raise ArchiveError("Studio Archive configuration version is unsupported.")
    raw_root = payload.get("archive_root")
    raw_scopes = payload.get("scopes")
    if not isinstance(raw_root, str) or not isinstance(raw_scopes, list):
        raise ArchiveError("Studio Archive configuration is malformed.")
    root = _validate_archive_root(Path(raw_root), state_dir)
    scopes: list[Scope] = []
    for item in raw_scopes:
        if not isinstance(item, dict):
            raise ArchiveError("Studio Archive scope configuration is malformed.")
        values = tuple(
            item.get(key) for key in ("scope_id", "relative_dir", "display_name")
        )
        if not all(isinstance(value, str) and value for value in values):
            raise ArchiveError("Studio Archive scope configuration is incomplete.")
        scope = Scope(
            scope_id=str(values[0]),
            relative_dir=str(values[1]),
            display_name=str(values[2]),
        )
        expected = _scope_from_relative(scope.relative_dir, root)
        if scope.scope_id != expected.scope_id:
            raise ArchiveError(
                "Studio Archive scope identifier does not match its path."
            )
        if scope.relative_dir != ".":
            relative = Path(scope.relative_dir)
            if (
                relative.is_absolute()
                or scope.relative_dir != relative.as_posix()
                or any(part in {"", ".", ".."} for part in relative.parts)
            ):
                raise ArchiveError(
                    "Configured archive scope is not a normalized relative path."
                )
        if validate_scope_roots:
            _resolve_scope_root(root, scope)
        scopes.append(scope)
    if not scopes or len({scope.scope_id for scope in scopes}) != len(scopes):
        raise ArchiveError("Studio Archive scopes must be non-empty and unique.")
    configured_at = str(payload.get("configured_at") or "")
    return ArchiveConfig(root, tuple(scopes), configured_at)


def _normalize_email_address(value: str) -> str:
    if not isinstance(value, str):
        raise ArchiveError("Client email addresses must be strings.")
    raw = value.strip()
    parsed = getaddresses([raw])
    if len(parsed) != 1:
        raise ArchiveError(f"Client email address is invalid: {value!r}.")
    address = parsed[0][1].strip().casefold()
    if (
        len(address) > 254
        or address.count("@") != 1
        or re.fullmatch(
            r"[A-Za-z0-9.!#$%&'*+/=?^_`|~-]+@[A-Za-z0-9.-]+",
            address,
        )
        is None
    ):
        raise ArchiveError(f"Client email address is invalid: {value!r}.")
    local_part, domain = address.rsplit("@", maxsplit=1)
    if (
        not local_part
        or not domain
        or domain.startswith((".", "-"))
        or domain.endswith((".", "-"))
        or ".." in domain
    ):
        raise ArchiveError(f"Client email address is invalid: {value!r}.")
    return address


def _normalize_email_addresses(values: Sequence[str]) -> tuple[str, ...]:
    if isinstance(values, (str, bytes)) or len(values) > MAX_CLIENT_EMAIL_ADDRESSES:
        raise ArchiveError(
            "A client may have at most "
            f"{MAX_CLIENT_EMAIL_ADDRESSES} confirmed email addresses."
        )
    normalized = {_normalize_email_address(value) for value in values}
    return tuple(sorted(normalized))


def _normalize_legal_names(values: Sequence[str]) -> tuple[str, ...]:
    if isinstance(values, (str, bytes)) or len(values) > MAX_CLIENT_LEGAL_NAMES:
        raise ArchiveError(
            f"A client may have at most {MAX_CLIENT_LEGAL_NAMES} legal names."
        )
    normalized: dict[str, str] = {}
    for value in values:
        if not isinstance(value, str):
            raise ArchiveError("Client legal names must be strings.")
        name = re.sub(r"\s+", " ", value).strip()
        if (
            not name
            or len(name) > 160
            or re.search(r"[\x00-\x1f\x7f]", name) is not None
        ):
            raise ArchiveError("Client legal names must contain 1 to 160 characters.")
        normalized.setdefault(name.casefold(), name)
    return tuple(normalized[key] for key in sorted(normalized))


def _normalize_tax_identifiers(values: Sequence[str]) -> tuple[str, ...]:
    if isinstance(values, (str, bytes)) or len(values) > MAX_CLIENT_TAX_IDENTIFIERS:
        raise ArchiveError(
            "A client may have at most "
            f"{MAX_CLIENT_TAX_IDENTIFIERS} tax identifiers."
        )
    normalized: set[str] = set()
    for value in values:
        if not isinstance(value, str):
            raise ArchiveError("Client tax identifiers must be strings.")
        identifier = re.sub(r"\s+", "", value).upper()
        # Swiss IDE punctuation is presentation only; keep one canonical identity.
        if re.fullmatch(r"CHE-?\d{3}\.?\d{3}\.?\d{3}", identifier):
            identifier = identifier.replace("-", "").replace(".", "")
        if re.fullmatch(r"[A-Z0-9]{5,32}", identifier) is None:
            raise ArchiveError(
                "Client tax identifiers must contain 5 to 32 letters or digits."
            )
        normalized.add(identifier)
    return tuple(sorted(normalized))


def _validate_identity_uniqueness(records: Sequence[ClientIdentity]) -> None:
    client_ids: set[str] = set()
    scope_ids: set[str] = set()
    email_owners: dict[str, str] = {}
    tax_owners: dict[str, str] = {}
    for record in records:
        if record.client_id in client_ids:
            raise ArchiveError("A stable client ID is assigned more than once.")
        if record.scope_id in scope_ids:
            raise ArchiveError("An archive scope is assigned to more than one client.")
        client_ids.add(record.client_id)
        scope_ids.add(record.scope_id)
        for email_address in record.email_addresses:
            previous_client = email_owners.setdefault(email_address, record.client_id)
            if previous_client != record.client_id:
                raise ArchiveError(
                    "Client email address is assigned to more than one client: "
                    f"{email_address}."
                )
        for tax_identifier in record.tax_identifiers:
            previous_client = tax_owners.setdefault(tax_identifier, record.client_id)
            if previous_client != record.client_id:
                raise ArchiveError(
                    "Client tax identifier is assigned to more than one client: "
                    f"{tax_identifier}."
                )


def _load_client_identities(state_dir: Path) -> tuple[ClientIdentity, ...]:
    return _load_client_identity_file(_client_identities_path(state_dir))


def _parse_client_identity(item: Any) -> ClientIdentity:
    """Validate one mechanical identity record independently of its siblings."""
    required = {
        "client_id",
        "scope_id",
        "email_addresses",
        "legal_names",
        "tax_identifiers",
        "updated_at",
    }
    if not isinstance(item, dict) or set(item) != required:
        raise ArchiveError("Studio Archive client identity record is malformed.")
    if (
        not isinstance(item["client_id"], str)
        or re.fullmatch(r"client_[0-9a-f]{24}", item["client_id"]) is None
        or not isinstance(item["scope_id"], str)
        or re.fullmatch(r"scope_[0-9a-f]{24}", item["scope_id"]) is None
        or not isinstance(item["updated_at"], str)
        or not item["updated_at"]
    ):
        raise ArchiveError("Studio Archive client identity record is invalid.")
    if not all(
        isinstance(item[key], list)
        for key in ("email_addresses", "legal_names", "tax_identifiers")
    ):
        raise ArchiveError("Studio Archive client identity values are malformed.")
    return ClientIdentity(
        client_id=item["client_id"],
        scope_id=item["scope_id"],
        email_addresses=_normalize_email_addresses(item["email_addresses"]),
        legal_names=_normalize_legal_names(item["legal_names"]),
        tax_identifiers=_normalize_tax_identifiers(item["tax_identifiers"]),
        updated_at=item["updated_at"],
    )


def _load_client_identity_file(
    path: Path, *, issues: list[dict[str, Any]] | None = None
) -> tuple[ClientIdentity, ...]:
    """Read aliases; partial readers preserve bad evidence and expose uncertainty."""
    try:
        if not path.exists() and not path.is_symlink():
            return ()
        _assert_private_file(path, "client identity registry")
        payload = preferences.read_json(path)
    except (ArchiveError, OSError, ValueError) as exc:
        if issues is not None:
            issues.append(
                {
                    "issue_code": "identity_registry_unavailable",
                    "reason": type(exc).__name__,
                    "available": False,
                }
            )
            return ()
        raise ArchiveError(
            f"Studio Archive client identity registry is unreadable: {exc}"
        ) from exc
    if (
        not isinstance(payload, dict)
        or payload.get("schema_version") != CLIENT_IDENTITIES_SCHEMA_VERSION
        or not isinstance(payload.get("clients"), list)
    ):
        if issues is not None:
            issues.append(
                {"issue_code": "identity_registry_malformed", "available": False}
            )
            return ()
        raise ArchiveError("Studio Archive client identity registry is malformed.")
    raw_clients = payload["clients"]
    if len(raw_clients) > MAX_CLIENT_IDENTITIES:
        if issues is not None:
            issues.append(
                {"issue_code": "identity_registry_limit_exceeded", "available": False}
            )
            return ()
        raise ArchiveError("Studio Archive client identity registry is too large.")
    records: list[ClientIdentity] = []
    for index, item in enumerate(raw_clients):
        try:
            records.append(_parse_client_identity(item))
        except ArchiveError:
            if issues is None:
                raise
            issues.append(
                {
                    "issue_code": "invalid_identity_record",
                    "record_index": index,
                    "available": False,
                }
            )
    if issues is None:
        _validate_identity_uniqueness(records)
    else:
        # A conflicting opaque ID/scope cannot authorize either alias record.
        # Shared email/tax aliases remain explicit ambiguous lookup candidates.
        clients: dict[str, int] = {}
        scopes: dict[str, int] = {}
        for record in records:
            clients[record.client_id] = clients.get(record.client_id, 0) + 1
            scopes[record.scope_id] = scopes.get(record.scope_id, 0) + 1
        unique = []
        for record in records:
            if clients[record.client_id] != 1 or scopes[record.scope_id] != 1:
                issues.append(
                    {
                        "issue_code": "conflicting_identity_record",
                        "client_id": record.client_id,
                        "scope_id": record.scope_id,
                        "available": False,
                    }
                )
            else:
                unique.append(record)
        records = unique
    return tuple(sorted(records, key=lambda record: record.client_id))


def _write_client_identities(
    state_dir: Path,
    records: Sequence[ClientIdentity],
) -> None:
    _validate_identity_uniqueness(records)
    _write_private_json(
        _client_identities_path(state_dir),
        {
            "schema_version": CLIENT_IDENTITIES_SCHEMA_VERSION,
            "clients": [
                record.as_json()
                for record in sorted(records, key=lambda item: item.client_id)
            ],
        },
    )


def _normalize_engagement_label(value: str) -> str:
    if not isinstance(value, str):
        raise ArchiveError("Engagement label must be text.")
    label = re.sub(r"\s+", " ", value).strip()
    if not label or len(label) > 160 or re.search(r"[\x00-\x1f\x7f]", label):
        raise ArchiveError("Engagement label must contain 1 to 160 characters.")
    return label


def _discover_ledger_clients(config: ArchiveConfig) -> tuple[dict[str, Any], ...]:
    """Read portable client IDs from exact top-level customer folders."""

    return tuple(_client_inventory(config)["clients"])


def _client_inventory(
    config: ArchiveConfig,
    records: Sequence[ClientIdentity] = (),
) -> dict[str, Any]:
    """Keep unavailable folders local to their scope; never adopt conflicting IDs."""

    unavailable = {issue["scope_id"] for issue in config.scope_issues}
    scoped_roots = [
        (scope.scope_id, config.archive_root / scope.relative_dir)
        for scope in config.scopes
        if scope.relative_dir != "." and scope.scope_id not in unavailable
    ]
    inventory = ledger.inspect_client_manifests(scoped_roots)
    inventory["blocked_clients"].extend(config.scope_issues)
    owners = {record.scope_id: record.client_id for record in records}
    valid = []
    for found in inventory["clients"]:
        owner = owners.get(found["scope_id"])
        if owner is not None and owner != found["client_id"]:
            inventory["blocked_clients"].append(
                {
                    "scope_id": found["scope_id"],
                    "issue_code": "conflicting_client_identity",
                    "reason": "Customer-folder identity conflicts with the registered client.",
                    "available": False,
                }
            )
        else:
            valid.append(found)
    inventory["clients"] = valid
    inventory["directory_issues"] = (
        [config.directory_issue] if config.directory_issue else []
    )
    inventory["complete"] = (
        not inventory["blocked_clients"] and not inventory["directory_issues"]
    )
    return inventory


def _merge_client_identities(
    records: list[ClientIdentity], config: ArchiveConfig
) -> tuple[tuple[ClientIdentity, ...], bool]:
    """Join verified portable IDs and private aliases without changing either."""
    by_client = {record.client_id: record for record in records}
    by_scope = {record.scope_id: record for record in records}
    changed = False
    for found in _client_inventory(config, records)["clients"]:
        client_id = found["client_id"]
        scope_id = found["scope_id"]
        existing = by_client.get(client_id)
        if existing is None:
            replacement = ClientIdentity(
                client_id=client_id,
                scope_id=scope_id,
                email_addresses=(),
                legal_names=(),
                tax_identifiers=(),
                updated_at=_now_iso(),
            )
            records.append(replacement)
            by_client[client_id] = replacement
            by_scope[scope_id] = replacement
            changed = True
            continue
        if existing.scope_id == scope_id:
            continue
        replacement = ClientIdentity(
            client_id=existing.client_id,
            scope_id=scope_id,
            email_addresses=existing.email_addresses,
            legal_names=existing.legal_names,
            tax_identifiers=existing.tax_identifiers,
            updated_at=_now_iso(),
        )
        records = [
            replacement if record.client_id == client_id else record
            for record in records
        ]
        by_client[client_id] = replacement
        by_scope.pop(existing.scope_id, None)
        by_scope[scope_id] = replacement
        changed = True
    return tuple(sorted(records, key=lambda record: record.client_id)), changed


@_identity_transaction
def _synchronize_client_identities(
    state_dir: Path, config: ArchiveConfig
) -> tuple[ClientIdentity, ...]:
    """Persist an explicit registry repair only after validating all retained aliases."""
    records, changed = _merge_client_identities(
        list(_load_client_identities(state_dir)), config
    )
    if changed:
        _write_client_identities(state_dir, records)
    return records


def _client_identity_view(
    state_dir: Path, config: ArchiveConfig
) -> tuple[tuple[ClientIdentity, ...], list[dict[str, Any]]]:
    """Serve healthy discovery without requiring registry maintenance or its lock."""
    issues: list[dict[str, Any]] = []
    shared = _client_identities_path(state_dir)
    legacy = state_dir / CLIENT_IDENTITIES_FILENAME
    source = shared
    records: tuple[ClientIdentity, ...] = ()
    try:
        if shared != legacy and not shared.exists() and legacy.is_file():
            source = legacy
    except OSError as exc:
        # Neither an inaccessible shared file nor an inaccessible legacy file
        # proves that no aliases exist. Preserve them and expose uncertainty.
        issues.append(
            {
                "issue_code": "identity_registry_unavailable",
                "reason": type(exc).__name__,
                "available": False,
            }
        )
    else:
        records = _load_client_identity_file(source, issues=issues)
    if source != shared and not issues:
        # One-time migration preserves fresh-chat aliases. A failed migration
        # must not obscure the readable current-session records.
        try:
            records = _synchronize_client_identities(state_dir, config)
        except (ArchiveError, OSError, ValueError) as exc:
            issues.append(
                {
                    "issue_code": "identity_migration_pending",
                    "reason": type(exc).__name__,
                    "available": False,
                }
            )
    merged, _ = _merge_client_identities(list(records), config)
    return merged, issues


def _client_record(
    record: ClientIdentity | None,
    *,
    scope: Scope,
) -> dict[str, Any]:
    if record is None:
        return {
            **scope.as_json(),
            "client_id": None,
            "registration_status": "unregistered",
            "profile_status": "alias_only",
            "email_addresses": [],
            "legal_names": [],
            "tax_identifiers": [],
            "updated_at": None,
        }
    profile_status = "configured" if record.email_addresses else "candidate_only"
    return {
        **scope.as_json(),
        "client_id": record.client_id,
        "registration_status": "registered",
        "profile_status": profile_status,
        "email_addresses": list(record.email_addresses),
        "legal_names": list(record.legal_names),
        "tax_identifiers": list(record.tax_identifiers),
        "updated_at": record.updated_at,
    }


def list_studio_client_identities(
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """List exact archive scopes and their private Gmail identity profiles."""

    private_state = _state_dir(state_dir)
    stored_config = _load_config(private_state, validate_scope_roots=False)
    config, scopes_changed = _current_scope_view(stored_config)
    records, identity_issues = _client_identity_view(private_state, config)
    records_by_scope = {record.scope_id: record for record in records}
    active_scope_ids = {scope.scope_id for scope in config.scopes}
    clients = [
        _client_record(records_by_scope.get(scope.scope_id), scope=scope)
        for scope in config.scopes
    ]
    orphaned = [
        {
            **record.as_json(),
            "profile_status": "orphaned",
        }
        for record in records
        if record.scope_id not in active_scope_ids
    ]
    return {
        "scope_configuration_changed": scopes_changed,
        "identity_registry_complete": not identity_issues,
        "identity_issues": identity_issues,
        "registered_client_count": sum(
            client["registration_status"] == "registered" for client in clients
        ),
        "unregistered_scope_count": sum(
            client["registration_status"] == "unregistered" for client in clients
        ),
        "configured_profile_count": sum(
            client["profile_status"] == "configured" for client in clients
        ),
        "candidate_only_profile_count": sum(
            client["profile_status"] == "candidate_only" for client in clients
        ),
        "alias_only_profile_count": sum(
            client["profile_status"] == "alias_only" for client in clients
        ),
        "orphaned_profile_count": len(orphaned),
        "clients": clients,
        "orphaned_profiles": orphaned,
        "gmail_connector_called": False,
    }


def _client_directory_record(
    record: ClientIdentity | None,
    *,
    scope: Scope | None,
) -> dict[str, Any]:
    """Project one private identity record onto its model-safe directory row.

    Exact identity values stay in the owner-only registry.  Counts preserve the
    operational distinction between an empty and configured profile without
    disclosing another client's email, legal-name aliases, or tax identifiers.
    """

    if scope is None:
        if record is None:
            raise ArchiveError("An orphaned client directory row requires a profile.")
        return {
            "client_id": record.client_id,
            "scope_id": record.scope_id,
            "registration_status": "orphaned",
            "profile_status": "orphaned",
            "identity_counts": {
                "email_addresses": len(record.email_addresses),
                "legal_names": len(record.legal_names),
                "tax_identifiers": len(record.tax_identifiers),
            },
        }
    if record is None:
        return {
            **scope.as_json(),
            "client_id": None,
            "registration_status": "unregistered",
            "profile_status": "alias_only",
            "identity_counts": {
                "email_addresses": 0,
                "legal_names": 0,
                "tax_identifiers": 0,
            },
        }
    return {
        **scope.as_json(),
        "client_id": record.client_id,
        "registration_status": "registered",
        "profile_status": (
            "configured" if record.email_addresses else "candidate_only"
        ),
        "identity_counts": {
            "email_addresses": len(record.email_addresses),
            "legal_names": len(record.legal_names),
            "tax_identifiers": len(record.tax_identifiers),
        },
    }


def normalize_studio_archive_layout(*, state_dir: Path | None = None) -> dict[str, Any]:
    """Normalize every visible project in the configured shared Archive."""
    config = _load_config(_state_dir(state_dir), validate_scope_roots=False)
    projects = sorted(
        path
        for path in config.archive_root.iterdir()
        if not path.name.startswith(".") and (path.is_dir() or path.is_symlink())
    )
    # Preflight the whole Archive before changing any project's folder names.
    for project in projects:
        ledger._layout().plan_project_layout(project)
    for project in projects:
        ledger.ensure_project_layout(project)
    return {
        "status": "normalized",
        "project_count": len(projects),
        "product_directories": list(ledger.PRODUCT_DIRECTORIES),
    }


def _has_product_files(client_root: Path) -> bool:
    """Count work in this product area, excluding its shared registry scaffolding."""
    area = ledger._product_root(client_root, ledger.product_directory())
    if not area.exists():
        return False
    for path in area.iterdir():
        if path.name.startswith(".") or path.name in {
            "client.json",
            "APRI ARCHIVIO.html",
            "Pratiche",
            "reporting",
        }:
            continue
        if path.is_symlink():
            continue
        if path.is_file():
            return True
        if path.is_dir() and any(
            item.is_file() and not item.is_symlink()
            for item in path.rglob("*")
            if not any(part.startswith(".") for part in item.relative_to(path).parts)
        ):
            return True
    return False


def list_studio_clients(
    *,
    state_dir: Path | None = None,
    include_location: bool = False,
) -> dict[str, Any]:
    """List client scopes without exposing the private identity registry."""

    private_state = _state_dir(state_dir)
    _restore_approved_root(private_state)
    if not _config_path(private_state).is_file():
        return {
            "configured": False,
            "scope_configuration_changed": False,
            "registered_client_count": 0,
            "unregistered_scope_count": 0,
            "configured_profile_count": 0,
            "candidate_only_profile_count": 0,
            "alias_only_profile_count": 0,
            "orphaned_profile_count": 0,
            "clients": [],
            "orphaned_profiles": [],
            "private_identity_values_returned": False,
            "gmail_connector_called": False,
            **_studio_archive_setup_contract(),
        }
    stored_config = _load_config(private_state, validate_scope_roots=False)
    config, scopes_changed = _current_scope_view(stored_config)
    records, identity_issues = _client_identity_view(private_state, config)
    inventory = _client_inventory(config, records)
    blocked = {issue["scope_id"]: issue for issue in inventory["blocked_clients"]}
    records_by_scope = {record.scope_id: record for record in records}
    active_scope_ids = {scope.scope_id for scope in config.scopes}
    clients = [
        (
            {
                **_client_directory_record(
                    records_by_scope.get(scope.scope_id), scope=scope
                ),
                **blocked[scope.scope_id],
                "registration_status": "blocked",
            }
            if scope.scope_id in blocked
            else _client_directory_record(
                records_by_scope.get(scope.scope_id), scope=scope
            )
        )
        for scope in config.scopes
    ]
    for client in clients:
        scope = next(
            scope for scope in config.scopes if scope.scope_id == client["scope_id"]
        )
        client_root = config.archive_root / scope.relative_dir
        try:
            client["product_has_work"] = _has_product_files(client_root)
            if client.get("registration_status") == "blocked":
                client["product_has_work"] = True
            elif client.get("client_id"):
                work = ledger.inspect_engagements(client_root, client["client_id"])
                client["product_has_work"] = bool(
                    client["product_has_work"]
                    or work["engagements"]
                    or work["blocked_engagements"]
                )
        except (OSError, ledger.LedgerError):
            # An unavailable area must not be silently represented as empty.
            client["product_has_work"] = True
    orphaned = [
        _client_directory_record(record, scope=None)
        for record in records
        if record.scope_id not in active_scope_ids
    ]
    return {
        "configured": True,
        **({"archive_location": str(config.archive_root)} if include_location else {}),
        "scope_configuration_changed": scopes_changed,
        "registered_client_count": sum(
            client["registration_status"] == "registered" for client in clients
        ),
        "unregistered_scope_count": sum(
            client["registration_status"] == "unregistered" for client in clients
        ),
        "configured_profile_count": sum(
            client["profile_status"] == "configured" for client in clients
        ),
        "candidate_only_profile_count": sum(
            client["profile_status"] == "candidate_only" for client in clients
        ),
        "alias_only_profile_count": sum(
            client["profile_status"] == "alias_only" for client in clients
        ),
        "orphaned_profile_count": len(orphaned),
        "clients": clients,
        "blocked_clients": inventory["blocked_clients"],
        "directory_complete": inventory["complete"] and not identity_issues,
        "directory_issues": inventory["directory_issues"],
        "scope_cache": _remember_known_scopes(private_state, config),
        "identity_registry_complete": not identity_issues,
        "identity_issues": identity_issues,
        "orphaned_profiles": orphaned,
        "private_identity_values_returned": False,
        "gmail_connector_called": False,
    }


def resolve_studio_client_identity(
    identity_kind: str,
    identity_value: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Resolve one user-supplied identity by exact local equality.

    Exact normalized equality is deterministic because it is an identity and
    security boundary.  This function does not rank semantic name similarity
    and never returns the stored registry values.
    """

    if identity_kind == "email_address":
        normalized: str = _normalize_email_address(identity_value)
        field = "email_addresses"
    elif identity_kind == "legal_name":
        normalized = _normalize_legal_names([identity_value])[0].casefold()
        field = "legal_names"
    elif identity_kind == "tax_identifier":
        normalized = _normalize_tax_identifiers([identity_value])[0]
        field = "tax_identifiers"
    else:
        raise ArchiveError(
            "identity_kind must be email_address, legal_name, or tax_identifier."
        )

    private_state = _state_dir(state_dir)
    stored_config = _load_config(private_state, validate_scope_roots=False)
    config, scopes_changed = _current_scope_view(stored_config)
    records, identity_issues = _client_identity_view(private_state, config)
    inventory = _client_inventory(config, records)
    blocked = {item["scope_id"]: item for item in inventory["blocked_clients"]}
    complete = not identity_issues and inventory["complete"]
    scopes_by_id = {scope.scope_id: scope for scope in config.scopes}
    matches: list[dict[str, Any]] = []
    for record in records:
        values = getattr(record, field)
        comparison_values = (
            {value.casefold() for value in values}
            if identity_kind == "legal_name"
            else set(values)
        )
        if normalized not in comparison_values:
            continue
        match = _client_directory_record(
            record, scope=scopes_by_id.get(record.scope_id)
        )
        if record.scope_id in blocked:
            match.update(blocked[record.scope_id], registration_status="blocked")
        matches.append(match)
    return {
        "resolution_status": (
            "exact_match"
            if len(matches) == 1
            else (
                "ambiguous_exact_match"
                if matches
                else "incomplete" if not complete else "no_exact_match"
            )
        ),
        "resolution_complete": complete,
        "directory_complete": inventory["complete"],
        "directory_issues": inventory["directory_issues"],
        "blocked_clients": inventory["blocked_clients"],
        "identity_issues": identity_issues,
        "identity_kind": identity_kind,
        "match_count": len(matches),
        "matches": matches,
        "private_identity_values_returned": False,
        "scope_configuration_changed": scopes_changed,
        "gmail_connector_called": False,
    }


def get_studio_client_folder(
    client_id: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Return a portable binding for one registered, stable client ID."""

    private_state = _state_dir(state_dir)
    stored_config = _load_config(private_state, validate_scope_roots=False)
    # The portable manifest owns this ID. Alias lookup and registry maintenance
    # are separate operations, not prerequisites for already selected work.
    config, _ = _current_scope_view(stored_config)
    inventory = _client_inventory(config)
    selected = next(
        (item for item in inventory["clients"] if item["client_id"] == client_id),
        None,
    )
    if selected is None:
        # A private pointer may explain an unavailable selection, but cannot
        # authorize a folder or prevent access to a verified portable identity.
        try:
            identity = next(
                (
                    item
                    for item in _load_client_identities(private_state)
                    if item.client_id == client_id
                ),
                None,
            )
        except (ArchiveError, OSError, ValueError):
            identity = None
        issue = next(
            (
                item
                for item in inventory["blocked_clients"]
                if item.get("client_id") == client_id
                or (identity is not None and item["scope_id"] == identity.scope_id)
            ),
            None,
        )
        if issue is not None:
            raise ArchiveError(f"Selected client is unavailable: {issue['reason']}")
        raise ArchiveError(
            "The selected client identity is unavailable in this archive."
        )
    scope = next(
        item for item in config.scopes if item.scope_id == selected["scope_id"]
    )
    if scope.relative_dir == ".":
        raise ArchiveError(
            "The archive root scope is not a client folder; select one immediate "
            "top-level client directory."
        )
    client_root = _resolve_scope_root(config.archive_root, scope)
    # Selection must verify this exact identity again, not trust a cached pointer.
    try:
        manifest = ledger.load_client_manifest(client_root)
    except (ledger.LedgerError, OSError) as exc:
        raise ArchiveError(f"Selected client identity is unavailable: {exc}") from exc
    if manifest["client_id"] != client_id:
        raise ArchiveError("Selected customer folder belongs to another client.")
    binding = build_studio_client_folder_binding(
        studio_client_id=client_id,
        scope_id=scope.scope_id,
        archive_root=config.archive_root,
        scope_relative_dir=scope.relative_dir,
        client_root=client_root,
        display_name=scope.display_name,
    )
    return {
        "status": "ready",
        "client_folder": binding,
        "directory_complete": inventory["complete"],
        "directory_issues": inventory["directory_issues"],
        "scope_cache": _remember_known_scopes(private_state, config),
        "blocked_clients": inventory["blocked_clients"],
        "source_archive_mutated": False,
        "gmail_connector_called": False,
    }


@_identity_transaction
def set_studio_client_identity(
    scope_id: str,
    *,
    email_addresses: Sequence[str] = (),
    legal_names: Sequence[str] = (),
    tax_identifiers: Sequence[str] = (),
    replace_orphaned_scope_id: str | None = None,
    general_workspace: bool = False,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Replace one scope's confirmed private Gmail identity profile."""

    private_state = _state_dir(state_dir)
    stored = _load_config(private_state, validate_scope_roots=False)
    config, _ = _current_scope_view(stored)
    scopes_by_id = {scope.scope_id: scope for scope in config.scopes}
    scope = scopes_by_id.get(scope_id)
    if scope is None:
        raise ArchiveError("Client identity scope is not configured.")
    if scope.relative_dir == ".":
        raise ArchiveError(
            "The archive root scope is not a client folder; select one immediate "
            "top-level client directory."
        )
    records = list(_synchronize_client_identities(private_state, config))
    existing = next(
        (record for record in records if record.scope_id == scope_id),
        None,
    )
    if replace_orphaned_scope_id is not None:
        if (
            not isinstance(replace_orphaned_scope_id, str)
            or re.fullmatch(
                r"scope_[0-9a-f]{24}",
                replace_orphaned_scope_id,
            )
            is None
        ):
            raise ArchiveError("Replacement client scope identifier is invalid.")
        if replace_orphaned_scope_id in scopes_by_id:
            raise ArchiveError(
                "Only an orphaned client profile can be explicitly rebound."
            )
        orphaned = next(
            (
                record
                for record in records
                if record.scope_id == replace_orphaned_scope_id
            ),
            None,
        )
        if orphaned is None:
            raise ArchiveError("Orphaned client profile was not found.")
        if existing is not None:
            raise ArchiveError(
                "The target client scope already has an identity profile."
            )
        if email_addresses or legal_names or tax_identifiers:
            raise ArchiveError(
                "Do not supply identity values while rebinding an orphaned profile."
            )
        replacement = ClientIdentity(
            client_id=orphaned.client_id,
            scope_id=scope_id,
            email_addresses=orphaned.email_addresses,
            legal_names=orphaned.legal_names,
            tax_identifiers=orphaned.tax_identifiers,
            updated_at=_now_iso(),
        )
        updated_records = [
            record for record in records if record.scope_id != replace_orphaned_scope_id
        ] + [replacement]
        try:
            ledger.create_client_manifest(
                _resolve_scope_root(config.archive_root, scope),
                replacement.client_id,
            )
        except ledger.LedgerError as exc:
            raise ArchiveError(f"Customer-folder ledger is invalid: {exc}") from exc
        _write_client_identities(private_state, updated_records)
        return {
            "status": "rebound",
            "client": _client_directory_record(replacement, scope=scope),
            "replaced_orphaned_scope_id": replace_orphaned_scope_id,
            "gmail_connector_called": False,
            "gmail_credentials_stored": False,
        }
    normalized_emails = _normalize_email_addresses(email_addresses)
    normalized_names = _normalize_legal_names(legal_names)
    normalized_tax_ids = _normalize_tax_identifiers(tax_identifiers)
    if not general_workspace and not (
        normalized_emails or normalized_names or normalized_tax_ids
    ):
        raise ArchiveError(
            "Configure at least one confirmed email address, legal name, "
            "or tax identifier."
        )
    unchanged = existing is not None and (
        existing.email_addresses == normalized_emails
        and existing.legal_names == normalized_names
        and existing.tax_identifiers == normalized_tax_ids
    )
    replacement = ClientIdentity(
        client_id=(
            existing.client_id
            if existing is not None
            else _new_private_id("client", {record.client_id for record in records})
        ),
        scope_id=scope_id,
        email_addresses=normalized_emails,
        legal_names=normalized_names,
        tax_identifiers=normalized_tax_ids,
        updated_at=existing.updated_at if unchanged else _now_iso(),
    )
    updated_records = [record for record in records if record.scope_id != scope_id] + [
        replacement
    ]
    _validate_identity_uniqueness(updated_records)
    try:
        ledger.create_client_manifest(
            _resolve_scope_root(config.archive_root, scope),
            replacement.client_id,
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Customer-folder ledger is invalid: {exc}") from exc
    if not unchanged:
        _write_client_identities(private_state, updated_records)
    return {
        "status": "unchanged" if unchanged else "configured",
        "client": _client_directory_record(replacement, scope=scope),
        "gmail_connector_called": False,
        "gmail_credentials_stored": False,
    }


def _safe_client_directory_name(legal_name: str) -> str:
    """Derive a portable display folder; the stable client ID remains separate."""

    normalized = _normalize_legal_names([legal_name])[0]
    name = re.sub(r'[<>:"/\\|?*\x00-\x1f\x7f]', " ", normalized)
    name = re.sub(r"\s+", " ", name).strip(" .")[:120].rstrip(" .")
    reserved = {
        "CON",
        "PRN",
        "AUX",
        "NUL",
        *{f"COM{number}" for number in range(1, 10)},
        *{f"LPT{number}" for number in range(1, 10)},
    }
    if not name or name.upper() in reserved or name in IGNORED_NAMES:
        raise ArchiveError(
            "The confirmed legal name cannot produce a safe client folder label."
        )
    return name


def _readable_after_write(
    function: Callable[..., dict[str, Any]],
) -> Callable[..., dict[str, Any]]:
    """Refresh derived navigation after a successful explicit archive mutation."""

    @wraps(function)
    def wrapped(*args: Any, **kwargs: Any) -> dict[str, Any]:
        result = function(*args, **kwargs)
        client_id = result.get("client_id") or result.get("run", {}).get("client_id")
        if client_id is None:
            client_id = result.get("client", {}).get("client_id")
        if client_id is not None:
            try:
                private_state = _state_dir(kwargs.get("state_dir"))
                client_root = _retained_scope_root(private_state, client_id)
                if client_root is None:
                    folder = get_studio_client_folder(
                        client_id, state_dir=private_state
                    )["client_folder"]
                    client_root = Path(folder["client_root"])
                from readable_archive import refresh_readable_archive

                result["readable_archive"] = refresh_readable_archive(
                    client_root, ledger
                )
            except (
                ArchiveError,
                ledger.LedgerError,
                OSError,
                UnicodeError,
                ImportError,
            ) as exc:
                # Ledger mutation remains committed; expose the separate view failure.
                result["readable_archive"] = {
                    "status": "unavailable",
                    "error": str(exc),
                }
        return result

    return wrapped


@_readable_after_write
@_identity_transaction
def create_studio_client(
    legal_name: str,
    *,
    email_addresses: Sequence[str] = (),
    tax_identifiers: Sequence[str] = (),
    general_workspace: bool = False,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Create an explicitly selected archive destination, without onboarding."""

    private_state = _state_dir(state_dir)
    stored = _load_config(private_state, validate_scope_roots=False)
    config, _ = _current_scope_view(stored)
    normalized_names = _normalize_legal_names([legal_name])
    normalized_emails = _normalize_email_addresses(email_addresses)
    normalized_tax_ids = _normalize_tax_identifiers(tax_identifiers)
    directory_name = _safe_client_directory_name(normalized_names[0])
    existing_by_name = {scope.relative_dir.casefold(): scope for scope in config.scopes}
    if directory_name.casefold() in existing_by_name:
        existing_scope = existing_by_name[directory_name.casefold()]
        raise ArchiveError(
            "A top-level folder already has the generated client label; select and "
            f"register existing scope {existing_scope.scope_id} instead."
        )
    records = list(_load_client_identities(private_state))
    client_id = _new_private_id("client", {record.client_id for record in records})
    client_root = config.archive_root / directory_name
    if client_root.exists() or client_root.is_symlink():
        raise ArchiveError("The generated client folder already exists.")
    client_root.mkdir()
    try:
        scope_issues: list[dict[str, Any]] = []
        current_scopes = _discover_top_level_scopes(
            config.archive_root, issues=scope_issues
        )
        scope = next(
            (item for item in current_scopes if item.relative_dir == directory_name),
            None,
        )
        if scope is None:
            raise ArchiveError("The new client folder was not discovered exactly.")
        record = ClientIdentity(
            client_id=client_id,
            scope_id=scope.scope_id,
            email_addresses=normalized_emails,
            legal_names=() if general_workspace else normalized_names,
            tax_identifiers=normalized_tax_ids,
            updated_at=_now_iso(),
        )
        try:
            ledger.create_client_manifest(client_root, client_id)
        except ledger.LedgerError as exc:
            raise ArchiveError(f"Customer-folder ledger is invalid: {exc}") from exc
        updated_records = [*records, record]
        _validate_identity_uniqueness(updated_records)
        updated_config = ArchiveConfig(
            archive_root=config.archive_root,
            scopes=current_scopes,
            configured_at=_now_iso(),
            scope_issues=tuple(scope_issues),
        )
        _write_private_json(_config_path(private_state), updated_config.as_json())
        try:
            _write_client_identities(private_state, updated_records)
        except (ArchiveError, OSError):
            _write_private_json(_config_path(private_state), config.as_json())
            raise
    except (ArchiveError, OSError) as exc:
        # The folder is already visible to the user and other processes. Even
        # on failed registration, recursive cleanup could erase their new work
        # or the portable identity that permits recovery without the registry.
        raise ArchiveError(
            f"Client registration could not finish; folder retained at {client_root}. "
            "Select the existing folder to resume registration. "
            f"Cause: {exc}"
        ) from exc
    folder = get_studio_client_folder(client_id, state_dir=private_state)
    _remember_known_scopes(private_state, updated_config)
    return {
        "status": "created",
        "client": _client_directory_record(record, scope=scope),
        "client_folder": folder["client_folder"],
        "relationship_setup_status": "not_requested",
        "workspace_kind": "general" if general_workspace else "client",
        "source_archive_mutated": True,
        "next_workflow": None,
    }


@_readable_after_write
def map_studio_legacy_incarichi(
    client_id: str,
    engagement_id: str,
    targets: list[dict[str, Any]],
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Add a reviewed explicit mapping without moving or rewriting old executions."""
    folder = Path(
        get_studio_client_folder(client_id, state_dir=state_dir)["client_folder"][
            "client_root"
        ]
    )
    try:
        result = ledger.incarichi().map_legacy(folder, engagement_id, targets)
    except ledger.LedgerError as exc:
        raise ArchiveError(str(exc)) from exc
    return {
        "client_id": client_id,
        "engagement_id": engagement_id,
        "saved": True,
        "mapping": result,
    }


@_readable_after_write
def begin_studio_incarico(
    client_id: str,
    engagement_id: str,
    workflow_id: str,
    purpose: str,
    *,
    originating_conversation: dict[str, str] | None = None,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Bind one job and its draft area before model or engine work begins."""
    folder = Path(
        get_studio_client_folder(client_id, state_dir=state_dir)["client_folder"][
            "client_root"
        ]
    )
    if originating_conversation is None and os.environ.get("CODEX_THREAD_ID"):
        originating_conversation = {
            "host": "codex",
            "thread_id": os.environ["CODEX_THREAD_ID"],
            "title": "Vai alla chat",
            "url": "",
        }
    try:
        result = ledger.incarichi().begin(
            folder, engagement_id, workflow_id, purpose, originating_conversation
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(str(exc)) from exc
    return {"client_id": client_id, "engagement_id": engagement_id, **result}


def get_studio_incarico(
    client_id: str, engagement_id: str, *, state_dir: Path | None = None
) -> dict[str, Any]:
    """Read saved assignment state through the selected Archive owner."""
    folder = Path(
        get_studio_client_folder(client_id, state_dir=state_dir)["client_folder"][
            "client_root"
        ]
    )
    try:
        return ledger.incarichi().overview(folder, engagement_id)
    except ledger.LedgerError as exc:
        raise ArchiveError(str(exc)) from exc


def read_studio_incarico_document(
    client_id: str,
    engagement_id: str,
    reference: dict[str, Any],
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Open one selected source or issued format without selecting it for execution."""
    folder = Path(
        get_studio_client_folder(client_id, state_dir=state_dir)["client_folder"][
            "client_root"
        ]
    )
    try:
        document = ledger.incarichi().document(folder, engagement_id, reference)
    except ledger.LedgerError as exc:
        raise ArchiveError(str(exc)) from exc
    path = Path(document["path"])
    preview = None
    if (
        path.suffix.lower() in {".md", ".txt", ".json", ".csv"}
        and document["byte_count"] <= 262144
    ):
        content = path.read_bytes()
        if hashlib.sha256(content).hexdigest() != document["sha256"]:
            raise ArchiveError("Document changed while opening it")
        try:
            preview = content.decode("utf-8-sig")
        except UnicodeDecodeError:
            preview = None
    return {**document, "preview": preview}


@_readable_after_write
def update_studio_incarico(
    client_id: str,
    engagement_id: str,
    fields: dict[str, Any],
    expected_revision: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Keep assignment revisions and refresh derived navigation independently."""
    folder = Path(
        get_studio_client_folder(client_id, state_dir=state_dir)["client_folder"][
            "client_root"
        ]
    )
    try:
        saved = ledger.incarichi().update(
            folder, engagement_id, fields, expected_revision
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(str(exc)) from exc
    return {"saved": True, **saved}


@_readable_after_write
def publish_studio_incarico_result(
    client_id: str,
    engagement_id: str,
    entry_key: str,
    label: str,
    files: list[dict[str, str]],
    expected_revision: int,
    idempotency_key: str,
    *,
    primary_format: str | None = None,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Publish one named result revision, with all its formats, through the shared ledger."""
    folder = Path(
        get_studio_client_folder(client_id, state_dir=state_dir)["client_folder"][
            "client_root"
        ]
    )
    try:
        # Read before publication so a metadata failure cannot disguise a saved result.
        conversations = ledger.incarichi().read(folder, engagement_id)["conversations"]
        result = ledger.deliverables().publish(
            folder,
            engagement_id,
            entry_key,
            label,
            files,
            expected_revision,
            idempotency_key,
            primary_format=primary_format,
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(str(exc)) from exc
    return {
        "client_id": client_id,
        "engagement_id": engagement_id,
        **result,
        "chat_association_warning": (
            None
            if conversations
            else "The result was saved, but this incarico has no associated chat. "
            "Retrieve the user-visible chat identity from the host and repeat begin "
            "with originating_conversation. Do not republish the documents. "
            "If identity is unavailable, deliver the result and disclose the missing link."
        ),
    }


@_readable_after_write
def reuse_studio_incarico_result(
    client_id: str,
    engagement_id: str,
    origin: dict[str, Any],
    role: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Resolve both explicit Archive identities and retain the exact selected version."""
    folder = Path(
        get_studio_client_folder(client_id, state_dir=state_dir)["client_folder"][
            "client_root"
        ]
    )
    origin_root = Path(
        get_studio_client_folder(origin["client_id"], state_dir=state_dir)[
            "client_folder"
        ]["client_root"]
    )
    try:
        result = ledger.incarichi().reuse(
            folder, engagement_id, origin_root, origin, role
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(str(exc)) from exc
    return {"client_id": client_id, "engagement_id": engagement_id, **result}


@_readable_after_write
def create_studio_client_engagement(
    client_id: str,
    engagement_label: str,
    *,
    idempotency_key: str | None = None,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Create one durable engagement inside the selected customer folder."""

    private_state = _state_dir(state_dir)
    folder = get_studio_client_folder(client_id, state_dir=private_state)[
        "client_folder"
    ]
    client_root = Path(folder["client_root"])
    try:
        label = _normalize_engagement_label(engagement_label)
        if idempotency_key is None:
            engagement = ledger.create_engagement(client_root, client_id, label)
            created = True
        else:
            outcome = ledger.ensure_engagement(
                client_root, client_id, label, idempotency_key=idempotency_key
            )
            engagement, created = outcome["engagement"], outcome["created"]
        inventory = ledger.inspect_inputs(client_root, engagement["engagement_id"])
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Customer-folder engagement is invalid: {exc}") from exc
    input_root = (
        ledger._engagement_root(client_root, engagement["engagement_id"]) / "inputs"
    )
    return {
        "status": "created" if created else "already_created",
        "client_id": client_id,
        "engagement": {
            **engagement,
            "imports": inventory["inputs"],
            "blocked_inputs": inventory["blocked_inputs"],
            "ledger_complete": inventory["complete"],
        },
        "input_dir": str(input_root.resolve(strict=True)),
        "source_archive_mutated": created,
    }


def _archive_organization_inventory_ref(snapshot_sha256: str) -> str:
    digest = hashlib.sha256(
        f"archive-organization-inventory-v1\0{snapshot_sha256}".encode("utf-8")
    ).hexdigest()
    return ARCHIVE_ORGANIZATION_INVENTORY_REF_PREFIX + digest[:24]


def _archive_organization_item_ref(
    snapshot_sha256: str,
    relative_path: str,
) -> str:
    digest = hashlib.sha256(
        ("archive-organization-item-v1\0" f"{snapshot_sha256}\0{relative_path}").encode(
            "utf-8"
        )
    ).hexdigest()
    return ARCHIVE_ORGANIZATION_ITEM_REF_PREFIX + digest[:24]


def _project_drive_relative_path(snapshot_sha256: str, relative_path: str) -> str:
    """Replace Drive-ID suffixes with stable unlinkable display references."""

    projected: list[str] = []
    for index, component in enumerate(relative_path.split("/")):
        match = re.fullmatch(
            r"(?P<label>.*)~(?P<drive_ref>[A-Za-z0-9_-]{12})", component
        )
        if match is None:
            projected.append(component)
            continue
        opaque = hashlib.sha256(
            (
                "archive-organization-path-component-v1\0"
                f"{snapshot_sha256}\0{index}\0{component}"
            ).encode("utf-8")
        ).hexdigest()[:10]
        projected.append(f"{match.group('label')}~ref_{opaque}")
    return "/".join(projected)


def _archive_organization_duplicate_key(
    item: Mapping[str, Any],
    *,
    storage_kind: str,
) -> str | None:
    if storage_kind == "local_filesystem":
        return str(item["sha256"])
    value = item.get("sha256_checksum")
    return str(value) if value else None


def _archive_organization_open_supported(
    item: Mapping[str, Any],
    *,
    storage_kind: str,
) -> bool:
    if storage_kind == "local_filesystem":
        return Path(str(item["relative_path"])).suffix.lower() in SUPPORTED_SUFFIXES
    capabilities = item.get("capabilities")
    if (
        not isinstance(capabilities, Mapping)
        or capabilities.get("can_download") is not True
    ):
        return False
    mime_type = str(item.get("mime_type") or "")
    if mime_type in GOOGLE_DRIVE_EXPORTS:
        return True
    if mime_type.startswith("application/vnd.google-apps."):
        return False
    return Path(
        str(item.get("name") or "")
    ).suffix.lower() in SUPPORTED_SUFFIXES or mime_type.startswith("text/")


def _project_archive_organization_inventory(
    snapshot: Mapping[str, Any],
) -> dict[str, Any]:
    """Return the full semantic inventory without execution-only identifiers."""

    snapshot_sha256 = str(snapshot["content_sha256"])
    storage_kind = (
        "google_drive"
        if snapshot.get("schema_version") == drive.DRIVE_SNAPSHOT_SCHEMA
        else "local_filesystem"
    )
    files = snapshot.get("files")
    if not isinstance(files, list):
        raise ArchiveError("Archive organization snapshot files are invalid.")
    refs_by_path = {
        str(item["relative_path"]): _archive_organization_item_ref(
            snapshot_sha256,
            str(item["relative_path"]),
        )
        for item in files
    }
    duplicate_paths: dict[str, list[str]] = {}
    for item in files:
        duplicate_key = _archive_organization_duplicate_key(
            item,
            storage_kind=storage_kind,
        )
        if duplicate_key is None:
            continue
        duplicate_paths.setdefault(duplicate_key, []).append(str(item["relative_path"]))
    canonical_by_path: dict[str, str] = {}
    duplicate_ref_by_path: dict[str, str] = {}
    for duplicate_key, paths in duplicate_paths.items():
        if len(paths) < 2:
            continue
        canonical = min(
            paths,
            key=lambda value: (
                len(Path(value).parts),
                value.casefold(),
                value,
            ),
        )
        group_ref = (
            ARCHIVE_ORGANIZATION_DUPLICATE_REF_PREFIX
            + hashlib.sha256(
                (
                    "archive-organization-exact-group-v1\0"
                    f"{snapshot_sha256}\0{duplicate_key}"
                ).encode("utf-8")
            ).hexdigest()[:20]
        )
        for relative_path in paths:
            canonical_by_path[relative_path] = canonical
            duplicate_ref_by_path[relative_path] = group_ref

    projected_files: list[dict[str, Any]] = []
    for item in files:
        relative_path = str(item["relative_path"])
        display_path = (
            _project_drive_relative_path(snapshot_sha256, relative_path)
            if storage_kind == "google_drive"
            else relative_path
        )
        canonical = canonical_by_path.get(relative_path)
        if storage_kind == "local_filesystem":
            modified_at = datetime.fromtimestamp(
                int(item["modified_ns"]) / 1_000_000_000,
                tz=timezone.utc,
            ).isoformat()
            size_bytes = int(item["byte_count"])
            mime_type = None
            name = Path(relative_path).name
        else:
            modified_at = str(item["modified_time"])
            size_bytes = item["size_bytes"]
            mime_type = str(item["mime_type"])
            name = str(item["name"])
        projected_files.append(
            {
                "item_ref": refs_by_path[relative_path],
                "relative_path": display_path,
                "name": name,
                "file_extension": Path(name).suffix.lower() or None,
                "mime_type": mime_type,
                "size_bytes": size_bytes,
                "modified_at": modified_at,
                "evidence_access": (
                    "available"
                    if _archive_organization_open_supported(
                        item,
                        storage_kind=storage_kind,
                    )
                    else "unsupported"
                ),
                "exact_duplicate_group": duplicate_ref_by_path.get(relative_path),
                "exact_duplicate_of": (
                    refs_by_path[canonical]
                    if canonical is not None and canonical != relative_path
                    else None
                ),
            }
        )
    excluded = snapshot.get("excluded")
    if not isinstance(excluded, list):
        raise ArchiveError("Archive organization snapshot exclusions are invalid.")
    projected_excluded = []
    for item in excluded:
        relative_path = str(item["relative_path"])
        projected_excluded.append(
            {
                "relative_path": (
                    _project_drive_relative_path(snapshot_sha256, relative_path)
                    if storage_kind == "google_drive"
                    else relative_path
                ),
                "reason": str(item["reason"]),
            }
        )
    return {
        "schema_version": ARCHIVE_ORGANIZATION_INVENTORY_SCHEMA,
        "inventory_ref": _archive_organization_inventory_ref(snapshot_sha256),
        "storage_kind": storage_kind,
        "root_name": snapshot.get("root_name"),
        "captured_at": str(snapshot["captured_at"]),
        "file_count": len(projected_files),
        "known_total_bytes": (
            int(snapshot["total_bytes"])
            if storage_kind == "local_filesystem"
            else int(snapshot["known_total_bytes"])
        ),
        "files": projected_files,
        "excluded": projected_excluded,
        "raw_hashes_returned": False,
        "drive_ids_returned": False,
        "absolute_paths_returned": False,
    }


def snapshot_studio_client_folder(
    client_id: str,
    engagement_id: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Capture and import a bounded file-identity snapshot for one client folder."""

    private_state = _state_dir(state_dir)
    root = _selected_ledger_root(client_id, engagement_id, state_dir=private_state)
    try:
        result = ledger.snapshot_client_folder(root, client_id, engagement_id)
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Client-folder snapshot failed: {exc}") from exc
    return {
        "status": result["status"],
        "input_id": result["input_id"],
        "model_inventory": _project_archive_organization_inventory(result["snapshot"]),
        "documents_copied": False,
        "source_archive_mutated": result["source_archive_mutated"],
    }


def _drive_bindings_digest(content: Mapping[str, Any]) -> str:
    return hashlib.sha256(
        json.dumps(
            content,
            ensure_ascii=False,
            sort_keys=True,
            separators=(",", ":"),
        ).encode("utf-8")
    ).hexdigest()


def _load_google_drive_bindings(state_dir: Path) -> list[dict[str, Any]]:
    path = _google_drive_bindings_path(state_dir)
    if not path.is_file():
        return []
    _assert_private_file(path, "Google Drive bindings")
    try:
        payload = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as exc:
        raise ArchiveError(f"Google Drive bindings are unreadable: {exc}") from exc
    if not isinstance(payload, dict) or set(payload) != {
        "schema_version",
        "bindings",
        "content_sha256",
    }:
        raise ArchiveError("Google Drive bindings are malformed.")
    content = {
        "schema_version": payload["schema_version"],
        "bindings": payload["bindings"],
    }
    if (
        payload["schema_version"] != GOOGLE_DRIVE_BINDINGS_SCHEMA
        or payload["content_sha256"] != _drive_bindings_digest(content)
        or not isinstance(payload["bindings"], list)
    ):
        raise ArchiveError("Google Drive bindings are invalid or stale.")
    normalized: list[dict[str, Any]] = []
    seen_clients: set[str] = set()
    seen_folders: set[str] = set()
    for item in payload["bindings"]:
        if not isinstance(item, dict) or set(item) != {
            "client_id",
            "folder_id",
            "drive_id",
            "display_name",
            "bound_at",
        }:
            raise ArchiveError("Google Drive binding shape is invalid.")
        client_id = str(item["client_id"])
        folder_id = str(item["folder_id"])
        if client_id in seen_clients or folder_id in seen_folders:
            raise ArchiveError("Google Drive bindings are not one-to-one.")
        if re.fullmatch(r"client_[0-9a-f]{24}", client_id) is None:
            raise ArchiveError("Google Drive binding client ID is invalid.")
        if re.fullmatch(r"[A-Za-z0-9_-]{3,256}", folder_id) is None:
            raise ArchiveError("Google Drive binding folder ID is invalid.")
        drive_id = item["drive_id"]
        if drive_id is not None and (
            not isinstance(drive_id, str)
            or re.fullmatch(r"[A-Za-z0-9_-]{3,256}", drive_id) is None
        ):
            raise ArchiveError("Google Drive binding Shared Drive ID is invalid.")
        display_name = str(item["display_name"]).strip()
        bound_at = str(item["bound_at"]).strip()
        if not display_name or not bound_at:
            raise ArchiveError("Google Drive binding metadata is invalid.")
        normalized.append(
            {
                "client_id": client_id,
                "folder_id": folder_id,
                "drive_id": drive_id,
                "display_name": display_name,
                "bound_at": bound_at,
            }
        )
        seen_clients.add(client_id)
        seen_folders.add(folder_id)
    return normalized


def _write_google_drive_bindings(
    state_dir: Path, bindings: Sequence[Mapping[str, Any]]
) -> None:
    ordered = sorted(
        (dict(item) for item in bindings), key=lambda item: item["client_id"]
    )
    content = {
        "schema_version": GOOGLE_DRIVE_BINDINGS_SCHEMA,
        "bindings": ordered,
    }
    _write_private_json(
        _google_drive_bindings_path(state_dir),
        {**content, "content_sha256": _drive_bindings_digest(content)},
    )


def authorize_studio_google_drive(
    client_secrets_path: Path,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Run the explicit Drive OAuth flow and store its token in private state."""

    private_state = _state_dir(state_dir, create=True)
    try:
        drive.authorize_google_drive(
            client_secrets_path,
            _google_drive_token_path(private_state),
        )
    except drive.DriveError as exc:
        raise ArchiveError(str(exc)) from exc
    return {
        "status": "authorized",
        "scope": drive.DRIVE_SCOPE,
        "token_path": str(_google_drive_token_path(private_state)),
        "credentials_persisted_privately": True,
        "external_service": "google-drive",
    }


def studio_google_drive_status(
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Report local authorization and client-to-folder bindings without an API call."""

    private_state = _state_dir(state_dir)
    token_path = _google_drive_token_path(private_state)
    if token_path.exists():
        _assert_private_file(token_path, "Google Drive token")
    bindings = _load_google_drive_bindings(private_state)
    return {
        "status": "ready" if token_path.is_file() else "authorization_required",
        "oauth_scope": drive.DRIVE_SCOPE,
        "restricted_scope": True,
        "token_present": token_path.is_file(),
        "binding_count": len(bindings),
        "bindings": bindings,
        "google_drive_api_called": False,
    }


def _drive_gateway(
    state_dir: Path,
    gateway: drive.DriveGateway | None,
) -> drive.DriveGateway:
    if gateway is not None:
        return gateway
    try:
        return drive.load_google_drive_gateway(_google_drive_token_path(state_dir))
    except drive.DriveError as exc:
        raise ArchiveError(str(exc)) from exc


def bind_studio_client_google_drive(
    client_id: str,
    folder_id: str,
    *,
    state_dir: Path | None = None,
    gateway: drive.DriveGateway | None = None,
) -> dict[str, Any]:
    """Bind one registered Studio Archive client to one exact Drive folder ID."""

    private_state = _state_dir(state_dir, create=True)
    get_studio_client_folder(client_id, state_dir=private_state)
    selected_gateway = _drive_gateway(private_state, gateway)
    try:
        folder = selected_gateway.get_file(folder_id)
    except drive.DriveError as exc:
        raise ArchiveError(str(exc)) from exc
    if (
        folder.get("mimeType") != drive.DRIVE_FOLDER_MIME_TYPE
        or folder.get("trashed") is True
    ):
        raise ArchiveError("Selected Google Drive item is not an active folder.")
    observed_id = folder.get("id")
    display_name = folder.get("name")
    if (
        observed_id != folder_id
        or not isinstance(display_name, str)
        or not display_name.strip()
        or len(display_name.strip()) > 768
    ):
        raise ArchiveError("Google Drive returned invalid root-folder metadata.")
    drive_id = folder.get("driveId")
    if drive_id is not None and (
        not isinstance(drive_id, str)
        or re.fullmatch(r"[A-Za-z0-9_-]{3,256}", drive_id) is None
    ):
        raise ArchiveError("Google Drive returned an invalid Shared Drive ID.")
    existing_bindings = _load_google_drive_bindings(private_state)
    if any(
        item["folder_id"] == folder_id and item["client_id"] != client_id
        for item in existing_bindings
    ):
        raise ArchiveError(
            "This Google Drive folder is already bound to another Vera client."
        )
    bindings = [item for item in existing_bindings if item["client_id"] != client_id]
    binding = {
        "client_id": client_id,
        "folder_id": folder_id,
        "drive_id": drive_id,
        "display_name": display_name.strip(),
        "bound_at": _now_iso(),
    }
    bindings.append(binding)
    _write_google_drive_bindings(private_state, bindings)
    return {
        "status": "bound",
        "binding": binding,
        "google_drive_api_called": True,
        "source_archive_mutated": False,
    }


def _google_drive_binding(client_id: str, state_dir: Path) -> dict[str, Any]:
    matches = [
        item
        for item in _load_google_drive_bindings(state_dir)
        if item["client_id"] == client_id
    ]
    if len(matches) != 1:
        raise ArchiveError(
            "Select and bind exactly one Google Drive folder for this client first."
        )
    return matches[0]


def snapshot_studio_client_google_drive(
    client_id: str,
    engagement_id: str,
    *,
    state_dir: Path | None = None,
    gateway: drive.DriveGateway | None = None,
) -> dict[str, Any]:
    """Snapshot one bound Drive tree and import only its immutable JSON receipt."""

    private_state = _state_dir(state_dir)
    client_root = _selected_ledger_root(
        client_id, engagement_id, state_dir=private_state
    )
    binding = _google_drive_binding(client_id, private_state)
    selected_gateway = _drive_gateway(private_state, gateway)
    try:
        snapshot = drive.snapshot_google_drive_folder(
            selected_gateway,
            binding["folder_id"],
            client_id,
            engagement_id,
        )
    except drive.DriveError as exc:
        raise ArchiveError(str(exc)) from exc
    if (
        snapshot["root_name"] != binding["display_name"]
        or snapshot["drive_id"] != binding["drive_id"]
    ):
        raise ArchiveError(
            "The bound Google Drive root changed identity; review the binding."
        )
    engagement_root = ledger._engagement_root(client_root, engagement_id)
    descriptor, temporary_name = tempfile.mkstemp(
        prefix=".vera-google-drive-snapshot-",
        suffix=".json",
        dir=engagement_root,
    )
    temporary = Path(temporary_name)
    try:
        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
            json.dump(snapshot, handle, ensure_ascii=False, indent=2, sort_keys=True)
            handle.write("\n")
            handle.flush()
            os.fsync(handle.fileno())
        imported = ledger.import_document(
            client_root,
            client_id,
            engagement_id,
            temporary,
            "source",
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Google Drive snapshot import failed: {exc}") from exc
    finally:
        temporary.unlink(missing_ok=True)
    return {
        "status": imported["status"],
        "input_id": imported["receipt"]["input_id"],
        "model_inventory": _project_archive_organization_inventory(snapshot),
        "documents_copied": False,
        "google_drive_api_called": True,
        "remote_archive_mutated": False,
        "studio_ledger_mutated": True,
    }


def _load_archive_organization_snapshot(
    client_id: str,
    engagement_id: str,
    snapshot_input_id: str,
    *,
    state_dir: Path,
) -> tuple[Path, dict[str, Any]]:
    client_root = _selected_ledger_root(
        client_id,
        engagement_id,
        state_dir=state_dir,
    )
    try:
        receipt = ledger.load_input_receipt(
            client_root,
            engagement_id,
            snapshot_input_id,
        )
    except ledger.LedgerError as exc:
        raise ArchiveError("Archive snapshot input is invalid.") from exc
    try:
        snapshot = json.loads(Path(receipt["path"]).read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as exc:
        raise ArchiveError("Archive snapshot is unreadable.") from exc
    if (
        not isinstance(snapshot, dict)
        or snapshot.get("schema_version")
        not in {ledger.FOLDER_SNAPSHOT_SCHEMA, drive.DRIVE_SNAPSHOT_SCHEMA}
        or snapshot.get("client_id") != client_id
        or snapshot.get("engagement_id") != engagement_id
    ):
        raise ArchiveError("Archive snapshot identity is invalid.")
    content = {key: value for key, value in snapshot.items() if key != "content_sha256"}
    if snapshot.get("content_sha256") != _drive_bindings_digest(content):
        raise ArchiveError("Archive snapshot digest is stale.")
    if snapshot["schema_version"] == drive.DRIVE_SNAPSHOT_SCHEMA:
        binding = _google_drive_binding(client_id, state_dir)
        if (
            snapshot.get("root_folder_id") != binding["folder_id"]
            or snapshot.get("root_name") != binding["display_name"]
            or snapshot.get("drive_id") != binding["drive_id"]
        ):
            raise ArchiveError("Google Drive snapshot binding is stale.")
    return client_root, snapshot


def get_studio_archive_organization_inventory(
    client_id: str,
    engagement_id: str,
    snapshot_input_id: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Return the resumable full-population semantic projection for one snapshot."""

    private_state = _state_dir(state_dir)
    _, snapshot = _load_archive_organization_snapshot(
        client_id,
        engagement_id,
        snapshot_input_id,
        state_dir=private_state,
    )
    return {
        "status": "ready",
        "input_id": snapshot_input_id,
        "model_inventory": _project_archive_organization_inventory(snapshot),
        "source_archive_mutated": False,
        "google_drive_api_called": False,
    }


def _bounded_extraction_payload(extraction: ExtractionResult) -> dict[str, Any]:
    text_parts: list[str] = []
    locators: list[dict[str, str]] = []
    consumed = 0
    for chunk in extraction.chunks:
        separator_length = 2 if text_parts else 0
        remaining = MAX_OPEN_CHARS - consumed - separator_length
        if remaining <= 0:
            break
        selected_text = chunk.text[:remaining]
        text_parts.append(selected_text)
        consumed += len(selected_text) + separator_length
        locators.append(
            {
                "kind": chunk.locator_kind,
                "value": chunk.locator_value,
            }
        )
    limitations = list(extraction.limitations)
    full_length = sum(len(chunk.text) for chunk in extraction.chunks) + 2 * max(
        0, len(extraction.chunks) - 1
    )
    if full_length > consumed:
        limitations.append("open_text_truncated")
    return {
        "status": extraction.status,
        "text": "\n\n".join(text_parts),
        "locators": locators,
        "extraction_method": extraction.extraction_method,
        "limitations": limitations,
    }


def open_studio_archive_organization_item(
    client_id: str,
    engagement_id: str,
    snapshot_input_id: str,
    item_ref: str,
    *,
    state_dir: Path | None = None,
    gateway: drive.DriveGateway | None = None,
) -> dict[str, Any]:
    """Open one snapshot item through an opaque model-facing reference."""

    if re.fullmatch(r"archive_item_[0-9a-f]{24}", item_ref) is None:
        raise ArchiveError("Archive organization item reference is invalid.")
    private_state = _state_dir(state_dir, create=True)
    client_root, snapshot = _load_archive_organization_snapshot(
        client_id,
        engagement_id,
        snapshot_input_id,
        state_dir=private_state,
    )
    snapshot_sha256 = str(snapshot["content_sha256"])
    files = snapshot.get("files")
    if not isinstance(files, list):
        raise ArchiveError("Archive snapshot files are invalid.")
    matches = [
        item
        for item in files
        if _archive_organization_item_ref(
            snapshot_sha256,
            str(item.get("relative_path") or ""),
        )
        == item_ref
    ]
    if len(matches) != 1:
        raise ArchiveError(
            "Archive organization item is not present exactly once in the snapshot."
        )
    expected = matches[0]
    storage_kind = (
        "google_drive"
        if snapshot["schema_version"] == drive.DRIVE_SNAPSHOT_SCHEMA
        else "local_filesystem"
    )
    relative_path = str(expected["relative_path"])
    display_path = (
        _project_drive_relative_path(snapshot_sha256, relative_path)
        if storage_kind == "google_drive"
        else relative_path
    )
    if storage_kind == "google_drive":
        opened = open_studio_google_drive_source(
            client_id,
            engagement_id,
            snapshot_input_id,
            str(expected["file_id"]),
            state_dir=private_state,
            gateway=gateway,
        )
        return {
            "status": opened["status"],
            "item_ref": item_ref,
            "storage_kind": storage_kind,
            "relative_path": display_path,
            "name": opened["name"],
            "mime_type": opened["mime_type"],
            "citation": f"archive-item:{item_ref} ({display_path})",
            "text": opened["text"],
            "locators": opened["locators"],
            "extraction_method": opened["extraction_method"],
            "evidence_mode": opened["evidence_mode"],
            "limitations": opened["limitations"],
            "source_identity_revalidated": True,
            "google_drive_api_called": True,
            "remote_archive_mutated": False,
            "temporary_content_deleted": True,
        }

    source = _resolve_source_file(client_root, relative_path, project_relative=True)
    if _sha256_file(source) != str(expected["sha256"]):
        raise SourceChangedError(
            "Local archive source changed after the selected snapshot."
        )
    extraction = _extract_document(source, enable_ocr=False)
    current_source = _resolve_source_file(
        client_root, relative_path, project_relative=True
    )
    if current_source != source or _sha256_file(current_source) != str(
        expected["sha256"]
    ):
        raise SourceChangedError(
            "Local archive source changed while the evidence was being read."
        )
    bounded = _bounded_extraction_payload(extraction)
    return {
        **bounded,
        "item_ref": item_ref,
        "storage_kind": storage_kind,
        "relative_path": display_path,
        "name": source.name,
        "mime_type": None,
        "citation": f"archive-item:{item_ref} ({display_path})",
        "evidence_mode": "local_read",
        "source_identity_revalidated": True,
        "google_drive_api_called": False,
        "source_archive_mutated": False,
    }


def open_studio_google_drive_source(
    client_id: str,
    engagement_id: str,
    snapshot_input_id: str,
    file_id: str,
    *,
    state_dir: Path | None = None,
    gateway: drive.DriveGateway | None = None,
) -> dict[str, Any]:
    """Revalidate and extract one bounded file from an immutable Drive snapshot."""

    private_state = _state_dir(state_dir, create=True)
    client_root = _selected_ledger_root(
        client_id, engagement_id, state_dir=private_state
    )
    binding = _google_drive_binding(client_id, private_state)
    try:
        receipt = ledger.load_input_receipt(
            client_root,
            engagement_id,
            snapshot_input_id,
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Google Drive snapshot input is invalid: {exc}") from exc
    try:
        snapshot = json.loads(Path(receipt["path"]).read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as exc:
        raise ArchiveError(f"Google Drive snapshot is unreadable: {exc}") from exc
    if (
        not isinstance(snapshot, dict)
        or snapshot.get("schema_version") != drive.DRIVE_SNAPSHOT_SCHEMA
        or snapshot.get("client_id") != client_id
        or snapshot.get("engagement_id") != engagement_id
        or snapshot.get("root_folder_id") != binding["folder_id"]
    ):
        raise ArchiveError("Google Drive snapshot identity is invalid.")
    content = {key: value for key, value in snapshot.items() if key != "content_sha256"}
    if snapshot.get("content_sha256") != _drive_bindings_digest(content):
        raise ArchiveError("Google Drive snapshot digest is stale.")
    files = snapshot.get("files")
    if not isinstance(files, list):
        raise ArchiveError("Google Drive snapshot files are invalid.")
    matches = [item for item in files if item.get("file_id") == file_id]
    if len(matches) != 1:
        raise ArchiveError("Drive file ID is not present exactly once in the snapshot.")
    expected = matches[0]
    selected_gateway = _drive_gateway(private_state, gateway)
    try:
        current = drive.normalize_file_metadata(
            selected_gateway.get_file(file_id), expected["parent_id"]
        )
    except drive.DriveError as exc:
        raise ArchiveError(str(exc)) from exc
    for key in (
        "file_id",
        "parent_id",
        "name",
        "mime_type",
        "version",
        "md5_checksum",
        "sha256_checksum",
        "drive_id",
    ):
        if current[key] != expected[key]:
            raise SourceChangedError(
                "Google Drive source changed after the selected snapshot."
            )
    if not current["capabilities"]["can_download"]:
        raise ArchiveError("Google Drive does not permit this file to be downloaded.")
    mime_type = current["mime_type"]
    export = GOOGLE_DRIVE_EXPORTS.get(mime_type)
    try:
        if export is not None:
            payload = selected_gateway.export_bytes(file_id, export[0])
            suffix = export[1]
            evidence_mode = "export"
        elif mime_type.startswith("application/vnd.google-apps."):
            raise ArchiveError(
                "This Google-native file type has no supported evidence export."
            )
        else:
            payload = selected_gateway.download_bytes(file_id)
            suffix = Path(current["name"]).suffix.lower()
            if suffix not in SUPPORTED_SUFFIXES:
                if mime_type.startswith("text/"):
                    suffix = ".txt"
                else:
                    raise ArchiveError(
                        "This Drive binary file type is not supported for extraction."
                    )
            evidence_mode = "download"
    except drive.DriveError as exc:
        raise ArchiveError(str(exc)) from exc
    if len(payload) > drive.MAX_EVIDENCE_BYTES:
        raise ArchiveError("Google Drive evidence exceeds the 100 MB read boundary.")
    try:
        current_after_read = drive.normalize_file_metadata(
            selected_gateway.get_file(file_id), expected["parent_id"]
        )
    except drive.DriveError as exc:
        raise ArchiveError(str(exc)) from exc
    for key in (
        "file_id",
        "parent_id",
        "name",
        "mime_type",
        "version",
        "md5_checksum",
        "sha256_checksum",
        "drive_id",
    ):
        if current_after_read[key] != expected[key]:
            raise SourceChangedError(
                "Google Drive source changed while the evidence was being read."
            )
    if evidence_mode == "download":
        if current["sha256_checksum"] is not None and (
            hashlib.sha256(payload).hexdigest() != current["sha256_checksum"]
        ):
            raise SourceChangedError(
                "Downloaded Google Drive evidence does not match its SHA-256."
            )
        if current["md5_checksum"] is not None and (
            hashlib.md5(payload, usedforsecurity=False).hexdigest()
            != current["md5_checksum"]
        ):
            raise SourceChangedError(
                "Downloaded Google Drive evidence does not match its MD5 checksum."
            )
    descriptor, temporary_name = tempfile.mkstemp(
        prefix=".vera-drive-evidence-",
        suffix=suffix,
        dir=private_state,
    )
    temporary = Path(temporary_name)
    try:
        with os.fdopen(descriptor, "wb") as handle:
            handle.write(payload)
            handle.flush()
            os.fsync(handle.fileno())
        extraction = _extract_document(temporary, enable_ocr=False)
    finally:
        temporary.unlink(missing_ok=True)
    bounded = _bounded_extraction_payload(extraction)
    return {
        **bounded,
        "client_id": client_id,
        "engagement_id": engagement_id,
        "snapshot_input_id": snapshot_input_id,
        "file_id": file_id,
        "relative_path": expected["relative_path"],
        "name": current["name"],
        "mime_type": mime_type,
        "version": current["version"],
        "citation": (
            f"gdrive:{file_id}@v{current['version']} " f"({expected['relative_path']})"
        ),
        "evidence_mode": evidence_mode,
        "google_drive_api_called": True,
        "remote_archive_mutated": False,
        "temporary_content_deleted": True,
    }


def _workflow_version(workflow_id: str) -> str:
    """Read the owning product/component version for the exact run identity."""

    components = Path(__file__).resolve().parents[2]
    component_root = components / {
        "agenzia-acquisition": "browser-automation",
        "fatture-xml-check": "client-file-preparation",
        "report-enti-locali": "report-builder",
    }.get(workflow_id, workflow_id)
    if workflow_id in {"contenzioso-tributario", "posizioni-negoziali"}:
        # This direct skill is released with Vera, not as a standalone component.
        component_root = (
            components.parent if components.name == "modules" else components / "vera"
        )
    manifest_path = component_root / ".codex-plugin" / "plugin.json"
    if not manifest_path.is_file():
        return "unversioned"
    try:
        payload = json.loads(manifest_path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as exc:
        raise ArchiveError(f"Workflow manifest is unreadable: {exc}") from exc
    version = payload.get("version") if isinstance(payload, dict) else None
    if not isinstance(version, str) or not version.strip():
        raise ArchiveError("Workflow manifest has no valid version.")
    return version.strip()


@_readable_after_write
def prepare_studio_client_workflow(
    engagement_id: str,
    workflow_id: str,
    *,
    input_ids: Sequence[str] = (),
    upstream_artifacts: Sequence[Mapping[str, Any]] = (),
    label: str | None = None,
    purpose: str | None = None,
    idempotency_key: str | None = None,
    new_run: bool = False,
    continue_from_run: str | None = None,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Prepare an exact, recoverable, idempotent customer-folder run."""

    if workflow_id not in CLIENT_WORKFLOW_IDS:
        raise ArchiveError("Workflow is not supported by the client engagement gate.")
    private_state = _state_location(state_dir)
    client_root = _retained_scope_root(private_state, None, engagement_id)
    if client_root is not None:
        client_id = ledger.load_engagement_manifest(client_root, engagement_id)[
            "client_id"
        ]
        inventory = {"blocked_clients": [], "complete": True, "directory_issues": []}
    else:
        config = _load_config(private_state, validate_scope_roots=False)
        current, _ = _current_scope_view(config)
        inventory = _client_inventory(current)
        matches: list[tuple[str, Scope]] = []
        for client in inventory["clients"]:
            scope = next(
                (
                    item
                    for item in current.scopes
                    if item.scope_id == client["scope_id"]
                ),
                None,
            )
            if scope is None:
                continue
            try:
                client_root = _resolve_scope_root(current.archive_root, scope)
                ledger.load_engagement_manifest(client_root, engagement_id)
            except (ArchiveError, ledger.LedgerError, OSError):
                continue
            matches.append((client["client_id"], scope))
        if not matches:
            raise ArchiveError("Client engagement was not found.")
        if len(matches) != 1:
            raise ArchiveError(
                "Client engagement identity is ambiguous across customer folders."
            )
        client_id, scope = matches[0]
        client_root = _resolve_scope_root(current.archive_root, scope)
    try:
        if continue_from_run is not None:
            if input_ids or upstream_artifacts or not idempotency_key:
                raise ArchiveError(
                    "Continuation uses the original sources and requires a fresh retry key."
                )
            original = ledger.load_run(client_root, engagement_id, continue_from_run)
            if original["run"]["workflow_id"] != workflow_id:
                raise ArchiveError("Continuation must select the original workflow.")
            inputs = original["input_manifest"]["inputs"]
            input_ids = [row["binding_id"] for row in inputs if row["kind"] == "import"]
            upstream_artifacts = [
                {
                    **(
                        {"engagement_id": row["upstream_engagement_id"]}
                        if "upstream_engagement_id" in row
                        else {}
                    ),
                    "run_id": row["upstream_run_id"],
                    "artifact_id": row["upstream_artifact_id"],
                    "role": row["role"],
                }
                for row in inputs
                if row["kind"] == "upstream_artifact"
            ]
            # Scope retries to this verified historical run. A distinct run
            # receives the current package when its first helper starts.
            idempotency_key = hashlib.sha256(
                (continue_from_run + "\0" + idempotency_key).encode()
            ).hexdigest()
            new_run = True
            label = label or original["run"]["label"]
            purpose = purpose or original["run"]["purpose"]
        ledger.incarichi().begin(
            client_root,
            engagement_id,
            workflow_id,
            purpose
            or label
            or ledger.load_engagement_manifest(client_root, engagement_id)["label"],
        )
        prepared = ledger.prepare_run(
            client_root,
            client_id,
            engagement_id,
            workflow_id,
            _workflow_version(workflow_id),
            input_ids=input_ids,
            upstream_artifacts=upstream_artifacts,
            label=label,
            purpose=purpose,
            idempotency_key=idempotency_key,
            new_run=new_run,
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Client workflow run is invalid: {exc}") from exc
    binding_status = _remember_run_binding(private_state, client_root, prepared)
    recovery = _checkpoint_work(private_state, prepared)
    return {
        "status": prepared["status"],
        "client_id": client_id,
        "engagement_id": engagement_id,
        "run": prepared["run"],
        "input_manifest": prepared["input_manifest"],
        "client_engagement": prepared["context"],
        "client_engagement_path": prepared["context_path"],
        "work_binding": binding_status,
        "recovery": recovery,
        "blocked_runs": prepared.get("blocked_runs", []),
        "blocked_clients": inventory["blocked_clients"],
        "directory_complete": inventory["complete"],
        "directory_issues": inventory["directory_issues"],
    }


def _journal_sampling_handoff_references(
    client_root: Path,
    engagement_id: str,
    sample_run_id: str,
) -> list[dict[str, str]]:
    """Resolve the exact closed artifacts for one mechanical workflow handoff."""

    try:
        loaded = ledger.load_run(client_root, engagement_id, sample_run_id)
        artifact_manifest = ledger.validate_run_artifacts(
            client_root,
            engagement_id,
            sample_run_id,
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Journal Sampling run is unavailable: {exc}") from exc
    run = loaded["run"]
    if run["workflow_id"] != "journal-sampling":
        raise ArchiveError("Selected sample run is not a Journal Sampling run.")
    if run["status"] not in {"ready_for_review", "completed"}:
        raise ArchiveError(
            "Journal Sampling must be review-ready or completed before Check Entries."
        )
    artifact_by_path = {
        artifact["path"]: artifact for artifact in artifact_manifest["artifacts"]
    }
    expected_paths = {
        path for path, _artifact_id, _role in JOURNAL_SAMPLING_CHECK_ENTRIES_HANDOFF
    }
    missing_paths = sorted(expected_paths - set(artifact_by_path))
    if missing_paths:
        raise ArchiveError(
            "Journal Sampling has no complete Check Entries handoff; "
            f"missing={missing_paths}."
        )
    references: list[dict[str, str]] = []
    for path, required_artifact_id, role in JOURNAL_SAMPLING_CHECK_ENTRIES_HANDOFF:
        artifact = artifact_by_path[path]
        if (
            required_artifact_id is not None
            and artifact["artifact_id"] != required_artifact_id
        ):
            raise ArchiveError(
                "Journal Sampling handoff has the wrong semantic artifact identity "
                f"for {path}."
            )
        references.append(
            {
                "run_id": sample_run_id,
                "artifact_id": artifact["artifact_id"],
                "role": role,
            }
        )
    return references


@_readable_after_write
def start_check_entries_from_sample(
    client_id: str,
    engagement_id: str,
    sample_run_id: str,
    *,
    support_input_ids: Sequence[str],
    source_engagement_id: str | None = None,
    label: str | None = None,
    purpose: str | None = None,
    idempotency_key: str | None = None,
    new_run: bool = False,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Prepare and start Check Entries from one exact sample and support batch."""

    private_state = _state_dir(state_dir)
    source_engagement_id = source_engagement_id or engagement_id
    root = _selected_ledger_root(
        client_id, source_engagement_id, state_dir=private_state, run_id=sample_run_id
    )
    destination = _selected_ledger_root(
        client_id, engagement_id, state_dir=private_state
    )
    if destination != root:
        raise ArchiveError(
            "Select source and destination incarichi in the same registered client"
        )
    if isinstance(support_input_ids, (str, bytes)) or not support_input_ids:
        raise ArchiveError("Select at least one support input for Check Entries.")
    normalized_support_ids = list(support_input_ids)
    if (
        not all(isinstance(input_id, str) for input_id in normalized_support_ids)
        or len(normalized_support_ids) > 10_000
        or len(set(normalized_support_ids)) != len(normalized_support_ids)
    ):
        raise ArchiveError("Check Entries support input selection is invalid.")
    try:
        support_receipts = [
            ledger.load_input_receipt(root, engagement_id, input_id)
            for input_id in normalized_support_ids
        ]
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Check Entries support input is invalid: {exc}") from exc
    if any(receipt["role"] != "support" for receipt in support_receipts):
        raise ArchiveError(
            "Check Entries accepts only inputs imported with the support role."
        )
    upstream_artifacts = _journal_sampling_handoff_references(
        root,
        source_engagement_id,
        sample_run_id,
    )
    if source_engagement_id != engagement_id:
        upstream_artifacts = [
            {**item, "engagement_id": source_engagement_id}
            for item in upstream_artifacts
        ]
    try:
        ledger.incarichi().begin(
            root,
            engagement_id,
            "check-entries",
            purpose or label or "Verifica documentale del campione selezionato",
        )
        prepared = ledger.prepare_run(
            root,
            client_id,
            engagement_id,
            "check-entries",
            _workflow_version("check-entries"),
            input_ids=normalized_support_ids,
            upstream_artifacts=upstream_artifacts,
            label=label or "Check sampled journal entries",
            purpose=(
                purpose
                or "Check one exact Journal Sampling sample against one support batch."
            ),
            idempotency_key=idempotency_key,
            new_run=new_run,
        )
        current_status = prepared["run"]["status"]
        if current_status in {"prepared", "failed"}:
            active = ledger.start_run(root, engagement_id, prepared["run"]["run_id"])
        elif current_status in {"running", "ready_for_review", "completed"}:
            active = prepared
        else:
            raise ArchiveError(
                "The existing Check Entries run is cancelled; request a new run."
            )
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Check Entries handoff could not start: {exc}") from exc
    binding_status = _remember_run_binding(private_state, root, active)
    recovery = _checkpoint_work(private_state, active)
    return {
        "status": active["run"]["status"],
        "preparation_status": prepared["status"],
        "client_id": client_id,
        "engagement_id": engagement_id,
        "sample_run_id": sample_run_id,
        "support_input_ids": normalized_support_ids,
        "run": active["run"],
        "input_manifest": active["input_manifest"],
        "client_engagement": active["context"],
        "client_engagement_path": active["context_path"],
        "work_binding": binding_status,
        "recovery": recovery,
    }


@_readable_after_write
def copy_studio_client_source_folder(
    client_id: str,
    engagement_id: str,
    source_path: Path,
    *,
    copy_authorized: bool,
    destination_name: str | None = None,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Copy an explicitly authorized external tree into client working files."""

    if copy_authorized is not True:
        raise ArchiveError(
            "Folder intake requires the user's explicit copy authorization."
        )
    private_state = _state_dir(state_dir)
    root = _selected_ledger_root(client_id, engagement_id, state_dir=private_state)
    folder = get_studio_client_folder(client_id, state_dir=private_state)[
        "client_folder"
    ]
    try:
        source = source_path.expanduser()
        if not source.is_absolute():
            raise ArchiveError("Select an absolute folder intake source.")
        resolved = source.resolve(strict=True)
        archive_root = Path(folder["archive_root"])
        if _path_is_within(resolved, archive_root) or _path_is_within(
            archive_root, resolved
        ):
            raise ArchiveError(
                "Folder intake must be external to the approved archive tree."
            )
        result = folder_intake.copy_source_folder(
            root,
            client_id,
            engagement_id,
            source,
            destination_name=destination_name,
        )
    except (ledger.LedgerError, OSError) as exc:
        raise ArchiveError(f"Client working-folder intake failed: {exc}") from exc
    return {**result, "client_id": client_id, "engagement_id": engagement_id}


def _inspect_import_source(
    source_path: Path, expected_sha256: str | None = None
) -> dict[str, Any]:
    """Probe access; optionally hash a transferred original without exposing bytes."""

    source = source_path.expanduser()
    # This prefix explains a failed access; it never rejects a readable file.
    chat_upload = PurePosixPath(str(source).replace("\\", "/")).parts[:4] == (
        "/",
        "mnt",
        "user-data",
        "uploads",
    )
    code = "source_unavailable"
    message = "The selected file cannot be opened on the computer running Archive."
    next_step = "Select the file from a folder this computer can access, then retry."
    try:
        if not source.is_absolute():
            code = "source_path_not_absolute"
            message = "Select the file's full path on the computer running Archive."
        else:
            resolved = source.resolve(strict=True)
            if source.is_symlink() or resolved != source:
                code = "source_path_is_symlink"
                message = "Select the original file, rather than a symbolic link."
            elif not stat.S_ISREG(source.stat().st_mode):
                code = "source_not_regular_file"
                message = "Select a file, rather than a folder or another kind of item."
            else:
                flags = os.O_RDONLY | getattr(os, "O_BINARY", 0)
                flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
                descriptor = os.open(source, flags)
                try:
                    if stat.S_ISREG(os.fstat(descriptor).st_mode):
                        result: dict[str, Any] = {
                            "source_path": str(source),
                            "reachable": True,
                        }
                        if expected_sha256 is not None:
                            # Exact hashes establish transfer identity, not document meaning.
                            before = os.fstat(descriptor)
                            digest = hashlib.sha256()
                            while chunk := os.read(descriptor, 1024 * 1024):
                                digest.update(chunk)
                            after = os.fstat(descriptor)
                            unchanged = all(
                                getattr(before, key) == getattr(after, key)
                                for key in (
                                    "st_dev",
                                    "st_ino",
                                    "st_size",
                                    "st_mtime_ns",
                                    "st_ctime_ns",
                                )
                            )
                            matches = (
                                unchanged and digest.hexdigest() == expected_sha256
                            )
                            result.update(
                                sha256=digest.hexdigest(),
                                byte_count=after.st_size,
                                matches_expected_sha256=matches,
                            )
                            if not matches:
                                result.update(
                                    code="source_digest_mismatch",
                                    message="The accessible file does not match the selected original attachment.",
                                    next_step="Copy the original file again without rewriting its contents, then verify it before importing. Reuse any existing client and engagement.",
                                )
                        return result
                    code = "source_not_regular_file"
                    message = "The selected item is no longer a regular file."
                finally:
                    os.close(descriptor)
    except PermissionError:
        code = "source_access_denied"
        message = "Archive does not have permission to open the selected file."
        next_step = "Allow access to that file or choose an accessible copy."
    except (FileNotFoundError, NotADirectoryError):
        code = "source_not_found"
        message = "The selected file was not found on the computer running Archive."
    except OSError as exc:
        message = (
            "The computer running Archive could not open the selected file "
            f"(system error {exc.errno})."
        )
    if chat_upload and code in {"source_not_found", "source_path_not_absolute"}:
        code = "source_not_on_device"
        message = "The file is in the chat, but the import tool looks for it on your computer."
        next_step = (
            "Use the host's supported file transfer to copy only the selected originals "
            "to an accessible working folder, then check their computer paths and "
            "original SHA-256 values with Archive. Offer Add folder from the + menu "
            "only when the current host offers it. If no transfer is available, ask "
            "the user to save those files in the accessible folder before creating "
            "a client, engagement or run. Do not copy into Archive's managed inputs "
            "directory. This path importer does not itself transfer chat attachments."
        )
    return {
        "source_path": str(source),
        "reachable": False,
        "code": code,
        "message": message,
        "next_step": next_step,
    }


def check_studio_import_sources(
    source_paths: Sequence[Path], *, expected_sha256: Sequence[str] | None = None
) -> dict[str, Any]:
    """Check input reachability on the import host before any durable creation."""

    if not source_paths or len(source_paths) > 100:
        raise ArchiveError("Select between 1 and 100 source paths per access check.")
    if expected_sha256 is not None and (
        len(expected_sha256) != len(source_paths)
        or any(
            not isinstance(value, str) or re.fullmatch(r"[0-9a-f]{64}", value) is None
            for value in expected_sha256
        )
    ):
        raise ArchiveError(
            "Supply one original lowercase SHA-256 per selected path, in the same order."
        )
    sources = [
        _inspect_import_source(
            path, expected_sha256[index] if expected_sha256 is not None else None
        )
        for index, path in enumerate(source_paths)
    ]
    ready = all(
        source["reachable"] and source.get("matches_expected_sha256", True)
        for source in sources
    )
    return {
        "schema_version": "vera.import_source_access.v1",
        "status": "ready" if ready else "action_required",
        "ready": ready,
        "checked_on": "archive_import_host",
        "sources": sources,
        "direct_chat_attachment_import_supported": False,
        "archive_records_created": False,
    }


@_readable_after_write
def import_studio_client_document(
    client_id: str,
    source_path: Path,
    role: str,
    *,
    engagement_id: str | None = None,
    engagement_label: str | None = None,
    expected_sha256: str | None = None,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Copy one authorized file into one explicit, immutable engagement input."""

    if role not in SUPPORTED_ENGAGEMENT_IMPORT_ROLES:
        raise ArchiveError("Import role must be journal, source, or support.")
    if engagement_id is None:
        raise ArchiveError(
            "Select or create an engagement before importing a document."
        )
    if engagement_label is not None:
        raise ArchiveError(
            "Engagement creation and document import are separate actions."
        )
    private_state = _state_location(state_dir)
    client_root = _selected_ledger_root(
        client_id, engagement_id, state_dir=private_state
    )
    engagement = ledger.load_engagement_manifest(client_root, engagement_id)
    if (
        expected_sha256 is not None
        and re.fullmatch(r"[0-9a-f]{64}", expected_sha256) is None
    ):
        raise ArchiveError(
            "Expected SHA-256 must be the original file's lowercase 64-digit digest."
        )
    source_access = _inspect_import_source(source_path, expected_sha256)
    if not source_access["reachable"] or not source_access.get(
        "matches_expected_sha256", True
    ):
        raise ArchiveImportSourceError(
            source_access, client_id=client_id, engagement_id=engagement_id
        )
    try:
        resolved_source = source_path.expanduser().resolve(strict=True)
        # A restored client can live beside ordinary user documents. Its parent
        # is not an Archive boundary; only configured roots and client ledgers are.
        archive_roots: set[Path] = set()
        try:
            archive_roots.add(
                _load_config(private_state, validate_scope_roots=False).archive_root
            )
        except ArchiveError:
            # Exact retained work remains usable without a session selection.
            pass
        foreign_scope = any(
            _path_is_within(resolved_source, root) for root in archive_roots
        ) or any(
            ledger._client_manifest_path(parent).exists()
            for parent in resolved_source.parents
        )
        if foreign_scope and not _path_is_within(resolved_source, client_root):
            raise ArchiveError(
                "Selected import source belongs to another Studio Archive scope."
            )
        imported = ledger.import_document(
            client_root,
            client_id,
            engagement_id,
            source_path,
            role,
            expected_sha256=expected_sha256,
        )
        inventory = ledger.inspect_inputs(client_root, engagement_id)
    except (ledger.LedgerError, OSError) as exc:
        source_access = _inspect_import_source(source_path, expected_sha256)
        if not source_access["reachable"] or not source_access.get(
            "matches_expected_sha256", True
        ):
            raise ArchiveImportSourceError(
                source_access, client_id=client_id, engagement_id=engagement_id
            ) from exc
        raise ArchiveError(f"Controlled document import failed: {exc}") from exc
    return {
        "status": imported["status"],
        "client_id": client_id,
        "engagement": {
            **engagement,
            "imports": inventory["inputs"],
            "blocked_inputs": inventory["blocked_inputs"],
            "ledger_complete": inventory["complete"],
        },
        "input_receipt": imported["receipt"],
        "input_id": imported["receipt"]["input_id"],
        "imported_path": imported["imported_path"],
        "original_preserved": True,
        "source_archive_mutated": imported["source_archive_mutated"],
        "deduplication_complete": imported["deduplication_complete"],
    }


def verify_studio_client_inputs(
    client_id: str,
    engagement_id: str,
    input_ids: Sequence[str],
    *,
    expected_receipts: Sequence[Mapping[str, Any]] | None = None,
    require_exact_input_set: bool = False,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Verify exact selected imports through the maintained portable readers."""

    private_state = _state_location(state_dir)
    root = _selected_ledger_root(client_id, engagement_id, state_dir=private_state)
    try:
        return input_verification.verify_inputs(
            root,
            client_id,
            engagement_id,
            input_ids,
            expected_receipts=expected_receipts,
            require_exact_input_set=require_exact_input_set,
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Input verification request failed: {exc}") from exc


def list_studio_client_engagements(
    client_id: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """List recoverable engagements, exact receipts, lifecycle, and artifacts."""

    private_state = _state_location(state_dir)
    client_root = _retained_scope_root(private_state, client_id)
    if client_root is None:
        folder = get_studio_client_folder(client_id, state_dir=private_state)[
            "client_folder"
        ]
        client_root = Path(folder["client_root"])
    try:
        engagement_inventory = ledger.inspect_engagements(client_root, client_id)
        stored_engagements = engagement_inventory["engagements"]
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Customer-folder ledger is invalid: {exc}") from exc
    engagements: list[dict[str, Any]] = []
    for engagement in stored_engagements:
        engagement_id = engagement["engagement_id"]
        try:
            input_inventory = ledger.inspect_inputs(client_root, engagement_id)
            imports = input_inventory["inputs"]
            inventory = ledger.inspect_runs(
                client_root, engagement_id, verify_inputs=False
            )
            stored_runs = inventory["runs"]
        except ledger.LedgerError as exc:
            raise ArchiveError(f"Customer-folder ledger is invalid: {exc}") from exc
        workflow_runs: list[dict[str, Any]] = []
        for loaded in stored_runs:
            run = loaded["run"]
            input_issue: str | None = None
            artifact_issue: str | None = None
            try:
                ledger.load_run(client_root, engagement_id, run["run_id"])
                inputs_valid = True
            except ledger.LedgerError as exc:
                inputs_valid = False
                input_issue = str(exc)
            artifacts = None
            artifacts_valid = False
            if run["status"] in {"ready_for_review", "completed"}:
                try:
                    artifacts = ledger.validate_run_artifacts(
                        client_root, engagement_id, run["run_id"]
                    )
                    artifacts_valid = True
                except ledger.LedgerError as exc:
                    artifact_issue = str(exc)
            available = (
                inputs_valid
                and artifacts_valid
                and run["status"] in {"ready_for_review", "completed"}
            )
            context = loaded["context"]
            output_dir = Path(loaded["output_dir"])
            record: dict[str, Any] = {
                "workflow_id": run["workflow_id"],
                "workflow_version": run["workflow_version"],
                "run_id": run["run_id"],
                "label": run["label"],
                "purpose": run["purpose"],
                "status": run["status"],
                "created_at": run["created_at"],
                "updated_at": run["updated_at"],
                "input_manifest": loaded["input_manifest"],
                "inputs_valid": inputs_valid,
                "input_issue": input_issue,
                "artifacts_available": available,
                "artifact_issue": artifact_issue,
                "artifact_manifest": artifacts,
                "run_output_dir": str(output_dir),
                "run_output_available": available,
                "client_engagement_path": loaded["context_path"],
                "client_engagement": context,
            }
            if run["workflow_id"] == "journal-sampling":
                record.update(
                    {
                        "normalized_journal_path": str(
                            output_dir / "normalization" / "normalized_journal.csv"
                        ),
                        "normalization_diagnostics_path": str(
                            output_dir
                            / "normalization"
                            / "normalization_diagnostics.json"
                        ),
                        "normalization_available": available
                        and (
                            output_dir / "normalization" / "normalized_journal.csv"
                        ).is_file()
                        and (
                            output_dir
                            / "normalization"
                            / "normalization_diagnostics.json"
                        ).is_file(),
                        "sample_output_dir": str(output_dir / "sample"),
                        "sample_available": available
                        and (output_dir / "sample" / "journal_sample.csv").is_file(),
                    }
                )
            elif run["workflow_id"] == "check-entries":
                record.update(
                    {
                        "checks_output_dir": str(output_dir / "checks"),
                        "checks_available": available
                        and (output_dir / "checks" / "check_audit.json").is_file(),
                    }
                )
            workflow_runs.append(record)
        engagements.append(
            {
                **engagement,
                "imports": imports,
                "blocked_inputs": input_inventory["blocked_inputs"],
                "workflow_run_count": len(workflow_runs)
                + len(inventory["blocked_runs"]),
                "workflow_runs": workflow_runs,
                "blocked_runs": inventory["blocked_runs"],
                "collection_issues": inventory["collection_issues"],
                "ledger_complete": inventory["complete"]
                and input_inventory["complete"],
            }
        )
    return {
        "client_id": client_id,
        "engagement_count": len(engagements),
        "engagements": engagements,
        "blocked_engagements": engagement_inventory["blocked_engagements"],
        "ledger_complete": engagement_inventory["complete"]
        and all(item["ledger_complete"] for item in engagements),
    }


def _run_binding_path(state: Path, identities: Sequence[str]) -> Path:
    """Locate an owner-private binding without consulting archive discovery."""
    owner = state.parent.resolve() / ".vera-work-continuity"
    for directory in (owner, owner / "work-bindings"):
        if directory.is_symlink():
            raise ArchiveError("Work continuity storage cannot be a symbolic link.")
        if directory.exists():
            info = directory.stat()
            if not stat.S_ISDIR(info.st_mode) or (
                os.name == "posix"
                and (info.st_uid != os.geteuid() or stat.S_IMODE(info.st_mode) & 0o077)
            ):
                raise ArchiveError("Work continuity storage must be owner-private.")
    key = hashlib.sha256("\0".join(identities).encode("utf-8")).hexdigest()
    return owner / "work-bindings" / f"{key}.json"


def _recovery_store(state: Path, identities: Sequence[str]) -> Path:
    owner = _archive_profile(state) or state
    key = hashlib.sha256("\0".join(identities).encode("utf-8")).hexdigest()
    return owner / "work-recovery" / key


def _checkpoint_work(state: Path, loaded: Mapping[str, Any]) -> dict[str, Any]:
    """A checkpoint failure must not hide the already committed professional work."""
    run = loaded["run"]
    try:
        from vera_assurance.recovery import checkpoint_run

        return checkpoint_run(
            Path(loaded["context_path"]),
            _recovery_store(
                state, (run["client_id"], run["engagement_id"], run["run_id"])
            ),
        )
    except (
        OSError,
        ValueError,
        KeyError,
        TypeError,
        sqlite3.Error,
        ImportError,
        ArchiveError,
    ) as exc:
        return {
            "status": "unavailable",
            "reason": type(exc).__name__,
            "retry_pending": True,
        }


def checkpoint_studio_client_workflow(
    client_id: str, engagement_id: str, run_id: str, *, state_dir: Path | None = None
) -> dict[str, Any]:
    """Retain exact admitted inputs and completed stages outside the destination."""
    state = _state_location(state_dir)
    root = _selected_ledger_root(
        client_id, engagement_id, state_dir=state, run_id=run_id
    )
    loaded = ledger.load_run(root, engagement_id, run_id)
    return {"run": loaded["run"], "recovery": _checkpoint_work(state, loaded)}


def restore_studio_client_workflow(
    client_id: str,
    engagement_id: str,
    run_id: str,
    destination: str | Path,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Restore the selected job to an explicitly authorized available destination."""
    from vera_assurance.recovery import restore_run

    state = _state_dir(state_dir)
    identities = (client_id, engagement_id, run_id)
    try:
        context_path = restore_run(
            _recovery_store(state, identities), Path(destination), identities
        )
        root = context_path.parents[5]
        loaded = ledger.load_run(root, engagement_id, run_id)
        # Run checkpoints retain admitted copies, not the engagement's original
        # input collection. Permit new imports without inventing missing receipts.
        ledger._ordinary_directory(
            ledger._engagement_root(root, engagement_id) / "inputs",
            label="restored engagement input directory",
            create=True,
        )
    except (
        OSError,
        ValueError,
        KeyError,
        TypeError,
        sqlite3.Error,
        ledger.LedgerError,
    ) as exc:
        raise ArchiveError(f"Run recovery destination is unavailable: {exc}") from exc
    return {
        "status": "restored",
        "run": loaded["run"],
        "client_engagement_path": str(context_path),
        "client_engagement": loaded["context"],
        "work_binding": _remember_run_binding(state, root, loaded),
        "recovery": {"status": "restored", "destination": str(root)},
    }


_EXPLICIT_RUN: ContextVar[dict[str, Any] | None] = ContextVar(
    "archive_run_context", default=None
)


@contextmanager
def use_studio_run_context(context_path: Path | None) -> Iterator[None]:
    """Continue an exact saved job even when secondary pointers cannot be written."""
    if context_path is None:
        yield
        return
    if (
        not context_path.is_absolute()
        or context_path.name != "context.json"
        or len(context_path.parents) < 6
    ):
        raise ArchiveError("Select an absolute canonical saved run context.")
    root = context_path.parents[5]
    loaded = ledger._load_run_identity(
        root, context_path.parents[2].name, context_path.parent.name
    )
    if Path(loaded["context_path"]) != context_path:
        raise ArchiveError("Context must be the canonical saved run context.")
    token = _EXPLICIT_RUN.set({**loaded["run"], "root": root})
    try:
        yield
    finally:
        _EXPLICIT_RUN.reset(token)


def retain_studio_run_binding(
    client_root: Path,
    engagement_id: str,
    run_id: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, str]:
    """Bind an already prepared portable run without changing archive selection."""
    # Exact manifest identities and hashes are mechanical evidence of the run;
    # later native operations revalidate them before using this private pointer.
    loaded = ledger.load_run(client_root, engagement_id, run_id)
    return _remember_run_binding(_state_location(state_dir), client_root, loaded)


def _remember_run_binding(
    state: Path, client_root: Path, loaded: Mapping[str, Any]
) -> dict[str, str]:
    """Retain admitted scope so losing session configuration cannot lose a job."""
    run = loaded["run"]
    record = {
        "schema_version": "vera.work_binding.v1",
        "client_id": run["client_id"],
        "engagement_id": run["engagement_id"],
        "run_id": run["run_id"],
        "static_sha256": run["static_sha256"],
        "client_root": str(client_root),
    }
    try:
        path = _run_binding_path(
            state, (run["client_id"], run["engagement_id"], run["run_id"])
        )
        path.parent.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
        _write_private_json(path, record)
    except (OSError, ValueError, ArchiveError) as exc:
        # Preparation is already durable. Failure to retain a second pointer
        # must not hide it or provoke duplicate creation; the exact context is
        # also returned and can be used to recover the same job.
        return {"status": "unavailable", "reason": type(exc).__name__}
    return {"status": "retained", "path": str(path)}


def _retained_run_root(
    state: Path, client_id: str, engagement_id: str, run_id: str
) -> Path | None:
    """Use the established job, verifying its identity without relisting clients."""
    explicit = _EXPLICIT_RUN.get()
    if explicit is not None:
        if (client_id, engagement_id, run_id) != tuple(
            explicit[key] for key in ("client_id", "engagement_id", "run_id")
        ):
            raise ArchiveError("Saved context belongs to a different selected run.")
        ledger._load_run_identity(explicit["root"], engagement_id, run_id)
        return explicit["root"]
    identities = (client_id, engagement_id, run_id)
    try:
        record = preferences.read_json(_run_binding_path(state, identities))
        if record is None:
            # Earlier installations kept the pointer inside Archive's profile.
            # Reuse it when available; new jobs no longer depend on that store.
            owner = _archive_profile(state) or state
            key = hashlib.sha256("\0".join(identities).encode("utf-8")).hexdigest()
            record = preferences.read_json(owner / "work-bindings" / f"{key}.json")
    except (OSError, ValueError, ArchiveError):
        return None
    if record is None or record.get("schema_version") != "vera.work_binding.v1":
        return None
    if (
        tuple(record.get(key) for key in ("client_id", "engagement_id", "run_id"))
        != identities
    ):
        return None
    stored_root = record.get("client_root")
    if not isinstance(stored_root, str) or not Path(stored_root).is_absolute():
        return None
    root = Path(stored_root)
    try:
        loaded = ledger._load_run_identity(root, engagement_id, run_id)
    except (OSError, ledger.LedgerError):
        # A moved folder can still be recovered by the ordinary portable-ID
        # lookup. An unrelated folder is never authorized by this pointer.
        return None
    run = loaded["run"]
    if run["client_id"] != client_id or run["static_sha256"] != record.get(
        "static_sha256"
    ):
        return None
    return root


def _retained_scope_root(
    state: Path, client_id: str | None, engagement_id: str | None = None
) -> Path | None:
    """Resolve exact portable IDs through verified run receipts, never names.

    Existing run bindings also cover engagement continuation and client reopen.
    Multiple live copies are ambiguous; choosing one could write to the wrong copy.
    """
    explicit = _EXPLICIT_RUN.get()
    if explicit is not None:
        if (client_id is not None and client_id != explicit["client_id"]) or (
            engagement_id is not None and engagement_id != explicit["engagement_id"]
        ):
            raise ArchiveError(
                "Saved context belongs to a different selected engagement."
            )
        ledger._load_run_identity(
            explicit["root"], explicit["engagement_id"], explicit["run_id"]
        )
        return explicit["root"]
    directories = {_run_binding_path(state, ()).parent}
    try:
        directories.add((_archive_profile(state) or state) / "work-bindings")
    except (OSError, ValueError, ArchiveError):
        pass  # Independent bindings still identify previously opened work.
    roots: dict[Path, Path] = {}
    for path in (
        path for directory in directories for path in directory.glob("*.json")
    ):
        try:
            record = preferences.read_json(path)
        except (OSError, ValueError, ArchiveError):
            continue
        if not isinstance(record, dict):
            continue
        selected_client = record.get("client_id")
        if not isinstance(selected_client, str) or (
            client_id is not None and selected_client != client_id
        ):
            continue
        selected_engagement = record.get("engagement_id")
        run_id = record.get("run_id")
        if not isinstance(selected_engagement, str) or not isinstance(run_id, str):
            continue
        if engagement_id is not None and selected_engagement != engagement_id:
            continue
        root = _retained_run_root(state, selected_client, selected_engagement, run_id)
        if root is not None:
            roots[root.resolve()] = (
                ledger._run_root(root, selected_engagement, run_id) / "context.json"
            )
    if len(roots) > 1:
        choices = "\n".join(str(roots[root]) for root in sorted(roots))
        raise ArchiveError(
            "Selected retained identity has multiple live locations. "
            "Select a saved context with --context before the command:\n" + choices
        )
    return next(iter(roots), None)


def _selected_ledger_root(
    client_id: str,
    engagement_id: str,
    *,
    state_dir: Path,
    run_id: str | None = None,
    retry_pending_reporting: bool = True,
) -> Path:
    if run_id is not None:
        retained = _retained_run_root(state_dir, client_id, engagement_id, run_id)
        if retained is not None:
            return retained
    else:
        retained = _retained_scope_root(state_dir, client_id, engagement_id)
        if retained is not None:
            return retained
    folder = get_studio_client_folder(client_id, state_dir=state_dir)["client_folder"]
    client_root = Path(folder["client_root"])
    try:
        engagement = ledger.load_engagement_manifest(client_root, engagement_id)
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Selected client engagement is invalid: {exc}") from exc
    if engagement["client_id"] != client_id:
        raise ArchiveError("Selected engagement belongs to another client.")
    if run_id is None or not retry_pending_reporting:
        return client_root
    try:
        # Recovery of another run must not take locks or make network calls on
        # the selected operation's critical path. Explicit maintenance can batch.
        ledger.retry_reporting(client_root, engagement_id=engagement_id, run_id=run_id)
    except (
        OSError,
        ValueError,
        KeyError,
        TypeError,
        ImportError,
        sqlite3.Error,
        ledger.LedgerError,
    ) as exc:
        logging.getLogger(__name__).warning(
            "Pending Archive reporting could not be retried: %s", type(exc).__name__
        )
    return client_root


def _deliver_run_metadata(
    loaded: Mapping[str, Any], result: dict[str, Any]
) -> dict[str, Any]:
    """Return committed work even when the optional metadata recorder cannot load."""
    try:
        if ledger._reporting_runtime().selective_reporting_enabled():
            from archive_reporting import metadata_result

            return metadata_result(loaded, result)
    except (
        OSError,
        ValueError,
        KeyError,
        TypeError,
        ImportError,
        sqlite3.Error,
    ) as exc:
        result["reporting"] = ledger._save_review_reporting(
            loaded, ledger._review_reporting_failure(loaded, exc)
        )
    return result


def _run_result(loaded: Mapping[str, Any]) -> dict[str, Any]:
    result = {"status": loaded["run"]["status"], "run": loaded["run"]}
    if "recovery" in loaded:
        result["recovery"] = loaded["recovery"]
    if "reporting" in loaded:
        result["reporting"] = loaded["reporting"]
        if loaded["reporting"].get("status") == "unavailable":
            # This acknowledgement contains lifecycle metadata only. Do not
            # obscure a committed state with another write to the failed recorder.
            return result
    return _deliver_run_metadata(loaded, result)


@_readable_after_write
def start_studio_client_workflow(
    client_id: str,
    engagement_id: str,
    run_id: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Mark one prepared run as running before executing helper scripts."""

    private_state = _state_location(state_dir)
    root = _selected_ledger_root(
        client_id, engagement_id, state_dir=private_state, run_id=run_id
    )
    try:
        loaded = ledger.start_run(root, engagement_id, run_id)
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Workflow run could not start: {exc}") from exc
    return _run_result({**loaded, "recovery": _checkpoint_work(private_state, loaded)})


def verify_studio_run_report(
    client_id: str,
    engagement_id: str,
    run_id: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Verify a selected run's saved report without triggering reporting recovery."""
    root = _selected_ledger_root(
        client_id,
        engagement_id,
        state_dir=_state_dir(state_dir),
        run_id=run_id,
        retry_pending_reporting=False,
    )
    try:
        return ledger.verify_run_report(root, engagement_id, run_id)
    except (ledger.LedgerError, OSError) as exc:
        raise ArchiveError(f"Report run could not be selected: {exc}") from exc


def write_studio_run_artifact(
    client_id: str,
    engagement_id: str,
    run_id: str,
    name: str,
    content: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Write one agent-authored text artifact through the Archive owner."""
    private_state = _state_location(state_dir)
    root = _selected_ledger_root(
        client_id, engagement_id, state_dir=private_state, run_id=run_id
    )
    try:
        loaded = ledger._load_run_identity(root, engagement_id, run_id)
        result = ledger.write_run_artifact(root, engagement_id, run_id, name, content)
    except (ledger.LedgerError, OSError) as exc:
        raise ArchiveError(f"Run artifact was not saved: {exc}") from exc
    # The successful owned save is a completed stage, including outside the
    # managed helper launcher. Retain it without hiding the write on backup failure.
    return {**result, "recovery": _checkpoint_work(private_state, loaded)}


def read_studio_run_artifact(
    client_id: str,
    engagement_id: str,
    run_id: str,
    path: str | Path,
    *,
    offset: int = 0,
    limit: int | None = None,
    columns: list[int] | None = None,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Return selected source units with locally retained, exact read provenance."""
    private_state = _state_location(state_dir)
    root = _selected_ledger_root(
        client_id, engagement_id, state_dir=private_state, run_id=run_id
    )
    loaded = ledger._load_run_identity(root, engagement_id, run_id)
    requested = Path(path).expanduser()
    if not requested.is_absolute():
        requested = Path(loaded["run_root"]) / requested
    if not requested.resolve().is_relative_to(Path(loaded["output_dir"]).resolve()):
        # Input reads still require the selected admitted bytes. Reading an
        # existing result does not require the source copies to remain available.
        loaded = ledger.load_run(root, engagement_id, run_id)
    ledger._reporting_runtime()
    from archive_reporting import read_artifact

    try:
        return read_artifact(
            loaded, Path(path), offset=offset, limit=limit, columns=columns
        )
    except (ValueError, OSError) as exc:
        raise ArchiveError(f"Run artifact could not be read: {exc}") from exc


@_readable_after_write
def fail_studio_client_workflow(
    client_id: str,
    engagement_id: str,
    run_id: str,
    reason: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Record a failed run while retaining its evidence and diagnostics."""

    private_state = _state_location(state_dir)
    root = _selected_ledger_root(
        client_id, engagement_id, state_dir=private_state, run_id=run_id
    )
    try:
        loaded = ledger.fail_run(root, engagement_id, run_id, reason)
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Workflow failure could not be recorded: {exc}") from exc
    return _run_result({**loaded, "recovery": _checkpoint_work(private_state, loaded)})


@_readable_after_write
def cancel_studio_client_workflow(
    client_id: str,
    engagement_id: str,
    run_id: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Cancel one abandoned run without deleting it."""

    private_state = _state_location(state_dir)
    root = _selected_ledger_root(
        client_id, engagement_id, state_dir=private_state, run_id=run_id
    )
    try:
        loaded = ledger.cancel_run(root, engagement_id, run_id)
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Workflow run could not be cancelled: {exc}") from exc
    return _run_result({**loaded, "recovery": _checkpoint_work(private_state, loaded)})


@_readable_after_write
def finalize_studio_client_workflow(
    client_id: str,
    engagement_id: str,
    run_id: str,
    artifacts: Sequence[Mapping[str, Any]] | None = None,
    *,
    expected_declaration_sha256: str | None = None,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """List the selected run's output paths, or seal its explicit declarations."""

    private_state = _state_location(state_dir)
    root = _selected_ledger_root(
        client_id, engagement_id, state_dir=private_state, run_id=run_id
    )
    try:
        if artifacts is None:
            if expected_declaration_sha256 is not None:
                raise ArchiveError("A declaration correction requires artifacts.")
            loaded = ledger.load_run(root, engagement_id, run_id)
            if loaded["run"]["status"] not in {"running", "ready_for_review"}:
                raise ArchiveError(
                    "Output declarations require a running or review-ready run."
                )
            output = Path(loaded["output_dir"])
            paths = [
                file.relative_to(output).as_posix()
                for file in ledger._output_files(output)
            ]
            result = {
                "status": "declaration_preview",
                "run_id": run_id,
                "output_paths": paths,
            }
            try:
                runtime = ledger._reporting_runtime()
                automatic = {
                    item["path"] for item in runtime.report_declarations(output)
                }
                result["output_paths"] = [
                    path for path in paths if path not in automatic
                ]
                if runtime.selective_reporting_enabled() and runtime.report_pipeline(
                    loaded["run"]["workflow_id"]
                ):
                    from archive_reporting import record_send
                    from archive_reporting_failure import (
                        REPORTING_ERRORS,
                        reporting_failure,
                    )

                    try:
                        record_send(
                            Path(loaded["run_root"]),
                            result,
                            channel="archive_declaration_preview",
                        )
                    except REPORTING_ERRORS as exc:
                        result["reporting"] = reporting_failure(
                            loaded["run"]["workflow_id"],
                            {},
                            exc,
                            stage="declaration_preview",
                            root=Path(loaded["run_root"]),
                        )
            except (
                OSError,
                ValueError,
                KeyError,
                TypeError,
                ImportError,
                sqlite3.Error,
            ) as exc:
                result["reporting"] = ledger._review_reporting_failure(loaded, exc)
            return result
        loaded = ledger.finalize_run(
            root,
            engagement_id,
            run_id,
            artifacts,
            expected_declaration_sha256=expected_declaration_sha256,
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Workflow artifacts could not be finalized: {exc}") from exc
    result = {
        "status": loaded["run"]["status"],
        "run": loaded["run"],
        "artifact_manifest": loaded["artifact_manifest"],
        "declaration_sha256": loaded["declaration_sha256"],
        "reporting": loaded["reporting"],
    }
    result["recovery"] = _checkpoint_work(private_state, loaded)
    if loaded["reporting"].get("status") == "unavailable":
        # Preserve the sealed outcome without re-entering the failed collector.
        return result
    return _deliver_run_metadata(loaded, result)


@_readable_after_write
def complete_studio_client_workflow(
    client_id: str,
    engagement_id: str,
    run_id: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Complete one review-ready run whose artifacts still validate."""

    private_state = _state_location(state_dir)
    root = _selected_ledger_root(
        client_id, engagement_id, state_dir=private_state, run_id=run_id
    )
    try:
        loaded = ledger.complete_run(root, engagement_id, run_id)
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Workflow run could not be completed: {exc}") from exc
    return _run_result({**loaded, "recovery": _checkpoint_work(private_state, loaded)})


@_readable_after_write
def close_studio_client_engagement(
    client_id: str,
    engagement_id: str,
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Close one engagement after every active run is resolved."""

    private_state = _state_location(state_dir)
    root = _selected_ledger_root(client_id, engagement_id, state_dir=private_state)
    try:
        engagement = ledger.close_engagement(root, engagement_id)
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Engagement could not be closed: {exc}") from exc
    return {"status": engagement["status"], "engagement": engagement}


def report_studio_client_retention(
    client_id: str,
    *,
    older_than_days: int | None = None,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Return a non-destructive retention inventory for professional review."""

    private_state = _state_dir(state_dir)
    folder = get_studio_client_folder(client_id, state_dir=private_state)[
        "client_folder"
    ]
    try:
        return ledger.retention_report(
            Path(folder["client_root"]), older_than_days=older_than_days
        )
    except ledger.LedgerError as exc:
        raise ArchiveError(f"Retention report could not be built: {exc}") from exc


def recover_studio_client_ledger(
    *,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Rebuild private client pointers and verify all portable ledger records."""

    private_state = _state_dir(state_dir)
    stored = _load_config(private_state, validate_scope_roots=False)
    current, _ = _current_scope_view(stored)
    identities, identity_issues = _client_identity_view(private_state, current)
    if not identity_issues:
        try:
            identities = _synchronize_client_identities(private_state, current)
        except (ArchiveError, OSError, ValueError) as exc:
            identity_issues.append(
                {
                    "issue_code": "identity_recovery_pending",
                    "reason": type(exc).__name__,
                    "available": False,
                }
            )
    client_inventory = _client_inventory(current, identities)
    engagement_count = 0
    input_count = 0
    run_count = 0
    blocked_runs: list[dict[str, Any]] = []
    blocked_engagements: list[dict[str, Any]] = []
    blocked_inputs: list[dict[str, Any]] = []
    collection_issues: list[dict[str, Any]] = []
    navigation_issues: list[dict[str, Any]] = []
    for client in client_inventory["clients"]:
        client_id = client["client_id"]
        root = Path(client["client_root"])
        try:
            catalogue = list_studio_client_engagements(
                client_id, state_dir=private_state
            )
            blocked_engagements.extend(
                {"client_id": client_id, **issue}
                for issue in catalogue["blocked_engagements"]
            )
            for engagement in catalogue["engagements"]:
                engagement_count += 1
                input_count += len(engagement["imports"])
                owner = {
                    "client_id": client_id,
                    "engagement_id": engagement["engagement_id"],
                }
                blocked_inputs.extend(
                    {**owner, **issue} for issue in engagement["blocked_inputs"]
                )
                blocked_runs.extend(
                    {**owner, **issue} for issue in engagement["blocked_runs"]
                )
                collection_issues.extend(
                    {**owner, **issue} for issue in engagement["collection_issues"]
                )
                for run in engagement["workflow_runs"]:
                    unavailable = not run["inputs_valid"] or (
                        run["status"]
                        in {
                            "ready_for_review",
                            "completed",
                        }
                        and not run["artifacts_available"]
                    )
                    if unavailable:
                        blocked_runs.append(
                            {
                                **owner,
                                "run_id": run["run_id"],
                                "issue_code": "invalid_run_evidence",
                                "reason": run["input_issue"] or run["artifact_issue"],
                                "available": False,
                            }
                        )
                    else:
                        run_count += 1
        except (ArchiveError, ledger.LedgerError, OSError) as exc:
            client_inventory["blocked_clients"].append(
                {
                    "client_id": client_id,
                    "scope_id": client["scope_id"],
                    "issue_code": "client_recovery_unavailable",
                    "reason": str(exc),
                    "available": False,
                }
            )
            continue
        try:
            from readable_archive import refresh_readable_archive

            refresh_readable_archive(root, ledger)
        except (ledger.LedgerError, OSError, UnicodeError, ImportError) as exc:
            navigation_issues.append({"client_id": client_id, "reason": str(exc)})
    complete = not any(
        (
            identity_issues,
            client_inventory["directory_issues"],
            client_inventory["blocked_clients"],
            blocked_engagements,
            blocked_inputs,
            blocked_runs,
            collection_issues,
            navigation_issues,
        )
    )
    return {
        "status": "recovered" if complete else "recovered_with_issues",
        "recovery_complete": complete,
        "identity_registry_complete": not identity_issues,
        "identity_issues": identity_issues,
        "directory_issues": client_inventory["directory_issues"],
        "blocked_clients": client_inventory["blocked_clients"],
        "blocked_engagements": blocked_engagements,
        "blocked_inputs": blocked_inputs,
        "blocked_runs": blocked_runs,
        "collection_issues": collection_issues,
        "navigation_issues": navigation_issues,
        "client_count": len(client_inventory["clients"]),
        "engagement_count": engagement_count,
        "input_count": input_count,
        "run_count": run_count,
        "private_identity_values_recovered": False,
    }


def _gmail_safe_phrase(value: str) -> str:
    normalized = re.sub(r'["{}\\():\[\]]', " ", value)
    normalized = re.sub(r"\s+", " ", normalized).strip()
    if not normalized:
        raise ArchiveError("Gmail search phrase contains no safe characters.")
    return f'"{normalized}"'


def _gmail_date(value: str | None, label: str) -> str | None:
    if value is None:
        return None
    if not isinstance(value, str) or re.fullmatch(r"\d{4}-\d{2}-\d{2}", value) is None:
        raise ArchiveError(f"{label} must use YYYY-MM-DD.")
    try:
        datetime.strptime(value, "%Y-%m-%d")
    except ValueError as exc:
        raise ArchiveError(f"{label} is not a valid calendar date.") from exc
    return value.replace("-", "/")


def _gmail_query_prefix(
    *,
    after: str | None,
    before: str | None,
) -> str:
    parts = ["in:anywhere", "-in:spam", "-in:trash"]
    normalized_after = _gmail_date(after, "after")
    normalized_before = _gmail_date(before, "before")
    if (
        normalized_after is not None
        and normalized_before is not None
        and normalized_after >= normalized_before
    ):
        raise ArchiveError("after must be earlier than before.")
    if normalized_after is not None:
        parts.append(f"after:{normalized_after}")
    if normalized_before is not None:
        parts.append(f"before:{normalized_before}")
    return " ".join(parts)


def _chunked(values: Sequence[str], size: int) -> Iterator[tuple[str, ...]]:
    for offset in range(0, len(values), size):
        yield tuple(values[offset : offset + size])


def plan_gmail_client_search(
    scope_id: str,
    *,
    topic: str | None = None,
    after: str | None = None,
    before: str | None = None,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Build bounded Gmail-native searches without calling the connector."""

    private_state = _state_dir(state_dir)
    stored = _load_config(private_state, validate_scope_roots=False)
    config, scopes_changed = _current_scope_view(stored)
    if scope_id == "all":
        raise ArchiveError("Studio-wide Gmail search is not supported.")
    scope = next((item for item in config.scopes if item.scope_id == scope_id), None)
    if scope is None:
        raise ArchiveError("Gmail search scope is not configured.")
    records, identity_issues = _client_identity_view(private_state, config)
    inventory = _client_inventory(config, records)
    issue = next(
        (item for item in inventory["blocked_clients"] if item["scope_id"] == scope_id),
        None,
    )
    if issue is not None:
        raise ArchiveError(f"Selected Gmail client is unavailable: {issue['reason']}")
    record = next((item for item in records if item.scope_id == scope_id), None)
    if topic is not None:
        if not isinstance(topic, str) or not topic.strip():
            raise ArchiveError("Gmail search topic must be non-empty when supplied.")
        if len(topic) > MAX_GMAIL_TOPIC_CHARS:
            raise ArchiveError(
                "Gmail search topic must contain at most "
                f"{MAX_GMAIL_TOPIC_CHARS} characters."
            )
        topic_phrase = _gmail_safe_phrase(topic)
    else:
        topic_phrase = None
    prefix = _gmail_query_prefix(after=after, before=before)
    topic_suffix = "" if topic_phrase is None else f" {topic_phrase}"
    queries: list[dict[str, Any]] = []
    if record is not None:
        for query_index, addresses in enumerate(
            _chunked(record.email_addresses, MAX_GMAIL_QUERY_IDENTITIES),
            start=1,
        ):
            participant_terms = " ".join(
                term
                for address in addresses
                for term in (
                    f"from:{address}",
                    f"to:{address}",
                    f"cc:{address}",
                    f"bcc:{address}",
                )
            )
            queries.append(
                {
                    "query_id": f"direct-{query_index}",
                    "kind": "confirmed_participant",
                    "query": f"{prefix} {{{participant_terms}}}{topic_suffix}",
                    "max_results": 20,
                    "routing_rule": "exact_unique_address_match_required",
                }
            )
        candidate_values = tuple(
            dict.fromkeys(
                (
                    scope.display_name,
                    *record.legal_names,
                    *record.tax_identifiers,
                )
            )
        )
    else:
        candidate_values = (scope.display_name,)
    for query_index, identities in enumerate(
        _chunked(candidate_values, MAX_GMAIL_QUERY_IDENTITIES),
        start=1,
    ):
        identity_terms = " ".join(_gmail_safe_phrase(value) for value in identities)
        queries.append(
            {
                "query_id": f"candidate-{query_index}",
                "kind": "identity_candidate",
                "query": f"{prefix} {{{identity_terms}}}{topic_suffix}",
                "max_results": 20,
                "routing_rule": "message_read_and_semantic_review_required",
            }
        )
    if record is None:
        profile_status = "alias_only"
    elif record.email_addresses:
        profile_status = "configured"
    else:
        profile_status = "candidate_only"
    return {
        "connector": "gmail",
        "scope_id": scope.scope_id,
        "display_name": scope.display_name,
        "profile_status": profile_status,
        "queries": queries,
        "scope_configuration_changed": scopes_changed,
        "directory_complete": inventory["complete"],
        "directory_issues": inventory["directory_issues"],
        "identity_registry_complete": not identity_issues,
        "identity_issues": identity_issues,
        "requires_connector_profile_check": True,
        "requires_message_read_before_use": True,
        "gmail_connector_called": False,
        "warnings": (
            []
            if record is not None and record.email_addresses
            else [
                "No confirmed participant address is configured. Candidate "
                "results must be reviewed and an address confirmed before "
                "automatic client routing."
            ]
        ),
    }


def match_studio_email_client(
    header_addresses: Sequence[str],
    *,
    headers_complete: bool = False,
    expected_scope_id: str | None = None,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Match Gmail headers only by unique, confirmed full email addresses."""

    if (
        isinstance(header_addresses, (str, bytes))
        or not header_addresses
        or len(header_addresses) > 100
    ):
        raise ArchiveError("Provide between 1 and 100 Gmail header address values.")
    if not isinstance(headers_complete, bool):
        raise ArchiveError("headers_complete must be a boolean.")
    private_state = _state_dir(state_dir)
    stored = _load_config(private_state, validate_scope_roots=False)
    config, scopes_changed = _current_scope_view(stored)
    scopes_by_id = {scope.scope_id: scope for scope in config.scopes}
    if expected_scope_id is not None and expected_scope_id not in scopes_by_id:
        raise ArchiveError("Expected Gmail client scope is not configured.")
    parsed_addresses: set[str] = set()
    unparsed_headers: list[str] = []
    for raw_header in header_addresses:
        if not isinstance(raw_header, str) or len(raw_header) > 2_000:
            raise ArchiveError("Gmail header address values must be bounded strings.")
        parsed = getaddresses([raw_header])
        accepted = False
        parsed_completely = bool(parsed)
        for _, address in parsed:
            if not address:
                parsed_completely = False
                continue
            try:
                parsed_addresses.add(_normalize_email_address(address))
            except ArchiveError:
                parsed_completely = False
                continue
            accepted = True
        if not accepted or not parsed_completely:
            unparsed_headers.append(raw_header)
    records, identity_issues = _client_identity_view(private_state, config)
    inventory = _client_inventory(config, records)
    blocked_scopes = {item["scope_id"] for item in inventory["blocked_clients"]}
    matched: dict[str, list[str]] = {}
    for record in records:
        addresses = sorted(parsed_addresses.intersection(record.email_addresses))
        if addresses:
            matched[record.scope_id] = addresses
    candidate_scope_ids = sorted(matched)
    unavailable_scope_ids = [
        scope_id
        for scope_id in candidate_scope_ids
        if scope_id not in scopes_by_id or scope_id in blocked_scopes
    ]
    header_coverage_complete = headers_complete and not unparsed_headers
    if len(candidate_scope_ids) > 1:
        routing_status = "ambiguous"
        matched_scope_id = None
    elif not header_coverage_complete or identity_issues or unavailable_scope_ids:
        routing_status = "incomplete"
        matched_scope_id = None
    elif len(candidate_scope_ids) == 1:
        routing_status = "exact"
        matched_scope_id: str | None = candidate_scope_ids[0]
    else:
        routing_status = "unassigned"
        matched_scope_id = None
    belongs_to_expected_scope: bool | None
    if expected_scope_id is None or matched_scope_id is None:
        belongs_to_expected_scope = None
    else:
        belongs_to_expected_scope = matched_scope_id == expected_scope_id
    return {
        "routing_status": routing_status,
        "matched_scope_id": matched_scope_id,
        "candidate_scope_ids": candidate_scope_ids,
        "matches": [
            {
                "scope_id": scope_id,
                "display_name": (
                    scopes_by_id[scope_id].display_name
                    if scope_id in scopes_by_id
                    else None
                ),
                "email_addresses": matched[scope_id],
                "match_method": "exact_email_address",
            }
            for scope_id in candidate_scope_ids
        ],
        "belongs_to_expected_scope": belongs_to_expected_scope,
        "may_use_in_scoped_answer": belongs_to_expected_scope is True,
        "requires_semantic_review": routing_status != "exact",
        "parsed_email_addresses": sorted(parsed_addresses),
        "unparsed_header_count": len(unparsed_headers),
        "header_coverage_complete": header_coverage_complete,
        "scope_configuration_changed": scopes_changed,
        "unavailable_scope_ids": unavailable_scope_ids,
        "identity_registry_complete": not identity_issues,
        "identity_issues": identity_issues,
        "gmail_connector_called": False,
        "gmail_data_persisted": False,
    }


def _config_fingerprint(config: ArchiveConfig) -> str:
    payload = json.dumps(
        {
            "schema_version": CONFIG_SCHEMA_VERSION,
            "archive_root": str(config.archive_root),
            "scopes": [scope.as_json() for scope in config.scopes],
        },
        sort_keys=True,
        separators=(",", ":"),
    )
    return _sha256_bytes(payload.encode("utf-8"))


def _connect(
    state_dir: Path,
    *,
    readonly: bool = False,
) -> sqlite3.Connection:
    path = _database_path(state_dir)
    if readonly:
        if not path.is_file():
            raise ArchiveError("Studio Archive index is missing; refresh it first.")
        _assert_private_file(path, "index")
        connection = sqlite3.connect(f"{path.as_uri()}?mode=ro", uri=True)
    else:
        connection = sqlite3.connect(path)
    connection.row_factory = sqlite3.Row
    connection.execute("PRAGMA foreign_keys = ON")
    if readonly:
        connection.execute("PRAGMA query_only = ON")
        try:
            schema_row = connection.execute(
                "SELECT value FROM metadata WHERE key = 'schema_version'"
            ).fetchone()
        except sqlite3.OperationalError as exc:
            connection.close()
            raise ArchiveError(
                "Studio Archive index is invalid; rebuild it before searching."
            ) from exc
        if schema_row is None or schema_row["value"] != SCHEMA_VERSION:
            connection.close()
            raise ArchiveError("Studio Archive database schema is unsupported.")
        return connection
    connection.execute("PRAGMA secure_delete = ON")
    connection.execute("PRAGMA journal_mode = DELETE")
    connection.executescript(
        """
        CREATE TABLE IF NOT EXISTS metadata (
            key TEXT PRIMARY KEY,
            value TEXT NOT NULL
        );
        CREATE TABLE IF NOT EXISTS documents (
            document_id TEXT PRIMARY KEY,
            scope_id TEXT NOT NULL,
            relative_path TEXT NOT NULL UNIQUE,
            extension TEXT NOT NULL,
            size_bytes INTEGER NOT NULL,
            mtime_ns INTEGER NOT NULL,
            sha256 TEXT NOT NULL,
            extraction_method TEXT NOT NULL,
            status TEXT NOT NULL,
            needs_ocr INTEGER NOT NULL,
            limitations_json TEXT NOT NULL,
            indexed_at TEXT NOT NULL,
            last_seen_generation INTEGER NOT NULL
        );
        CREATE TABLE IF NOT EXISTS chunks (
            source_id TEXT PRIMARY KEY,
            document_id TEXT NOT NULL REFERENCES documents(document_id)
                ON DELETE CASCADE,
            ordinal INTEGER NOT NULL,
            locator_kind TEXT NOT NULL,
            locator_value TEXT NOT NULL,
            text TEXT NOT NULL,
            text_sha256 TEXT NOT NULL,
            UNIQUE(document_id, ordinal)
        );
        CREATE TABLE IF NOT EXISTS scan_issues (
            relative_path TEXT PRIMARY KEY,
            scope_id TEXT NOT NULL,
            reason TEXT NOT NULL,
            size_bytes INTEGER
        );
        CREATE VIRTUAL TABLE IF NOT EXISTS chunk_fts USING fts5(
            source_id UNINDEXED,
            text,
            tokenize = 'unicode61 remove_diacritics 2'
        );
        CREATE INDEX IF NOT EXISTS documents_scope_idx
            ON documents(scope_id, relative_path);
        CREATE INDEX IF NOT EXISTS chunks_document_idx
            ON chunks(document_id, ordinal);
        """
    )
    try:
        connection.execute(
            "INSERT INTO chunk_fts(chunk_fts, rank) VALUES('secure-delete', 1)"
        )
    except sqlite3.OperationalError as exc:
        connection.close()
        raise ArchiveError(
            "The active SQLite FTS5 runtime does not support secure deletion."
        ) from exc
    connection.execute(
        "INSERT OR IGNORE INTO metadata(key, value) VALUES('schema_version', ?)",
        (SCHEMA_VERSION,),
    )
    schema_row = connection.execute(
        "SELECT value FROM metadata WHERE key = 'schema_version'"
    ).fetchone()
    if schema_row is None or schema_row["value"] != SCHEMA_VERSION:
        connection.close()
        raise ArchiveError("Studio Archive database schema is unsupported.")
    connection.commit()
    try:
        path.chmod(0o600)
    except OSError:
        connection.close()
        raise
    return connection


def _metadata_get(connection: sqlite3.Connection, key: str) -> str | None:
    row = connection.execute(
        "SELECT value FROM metadata WHERE key = ?",
        (key,),
    ).fetchone()
    return None if row is None else str(row["value"])


def _metadata_set(connection: sqlite3.Connection, key: str, value: str) -> None:
    connection.execute(
        """
        INSERT INTO metadata(key, value) VALUES(?, ?)
        ON CONFLICT(key) DO UPDATE SET value = excluded.value
        """,
        (key, value),
    )


def _clear_index(connection: sqlite3.Connection) -> None:
    connection.execute("DELETE FROM chunk_fts")
    connection.execute("DELETE FROM chunks")
    connection.execute("DELETE FROM documents")
    connection.execute("DELETE FROM scan_issues")


def _replace_scan_issues(
    connection: sqlite3.Connection,
    issues: Sequence[ScanIssue],
) -> None:
    connection.execute("DELETE FROM scan_issues")
    connection.executemany(
        """
        INSERT INTO scan_issues(relative_path, scope_id, reason, size_bytes)
        VALUES (?, ?, ?, ?)
        """,
        (
            (
                issue.relative_path,
                issue.scope_id,
                issue.reason,
                issue.size_bytes,
            )
            for issue in issues
        ),
    )


def _scan_issue_status(
    connection: sqlite3.Connection,
    *,
    scope_id: str | None = None,
) -> dict[str, Any]:
    issue_count = int(
        connection.execute(
            """
            SELECT COUNT(*) AS count
            FROM scan_issues
            WHERE ? IS NULL OR scope_id = ?
            """,
            (scope_id, scope_id),
        ).fetchone()["count"]
    )
    rows = connection.execute(
        """
        SELECT scope_id, relative_path, reason, size_bytes
        FROM scan_issues
        WHERE ? IS NULL OR scope_id = ?
        ORDER BY relative_path
        LIMIT ?
        """,
        (scope_id, scope_id, MAX_STATUS_SCAN_ISSUES),
    ).fetchall()
    return {
        "scan_issue_count": issue_count,
        "scan_issues": [
            {
                "scope_id": str(row["scope_id"]),
                "relative_path": str(row["relative_path"]),
                "reason": str(row["reason"]),
                "size_bytes": (
                    None if row["size_bytes"] is None else int(row["size_bytes"])
                ),
            }
            for row in rows
        ],
        "scan_issues_truncated": issue_count > len(rows),
    }


def _document_issue_status(
    connection: sqlite3.Connection,
    *,
    scope_id: str | None = None,
) -> dict[str, Any]:
    """Return a bounded inventory of indexed documents with evidence limits."""

    issue_count = int(
        connection.execute(
            """
            SELECT COUNT(*) AS count
            FROM (
                SELECT d.document_id
                FROM documents AS d
                LEFT JOIN chunks AS c ON c.document_id = d.document_id
                WHERE ? IS NULL OR d.scope_id = ?
                GROUP BY d.document_id
                HAVING d.status != 'indexed'
                    OR d.needs_ocr = 1
                    OR d.limitations_json != '[]'
                    OR COUNT(c.source_id) = 0
            )
            """,
            (scope_id, scope_id),
        ).fetchone()["count"]
    )
    rows = connection.execute(
        """
        SELECT
            d.scope_id,
            d.relative_path,
            d.status,
            d.needs_ocr,
            d.limitations_json,
            COUNT(c.source_id) AS chunk_count
        FROM documents AS d
        LEFT JOIN chunks AS c ON c.document_id = d.document_id
        WHERE ? IS NULL OR d.scope_id = ?
        GROUP BY
            d.document_id,
            d.scope_id,
            d.relative_path,
            d.status,
            d.needs_ocr,
            d.limitations_json
        HAVING d.status != 'indexed'
            OR d.needs_ocr = 1
            OR d.limitations_json != '[]'
            OR COUNT(c.source_id) = 0
        ORDER BY d.relative_path
        LIMIT ?
        """,
        (scope_id, scope_id, MAX_STATUS_DOCUMENT_ISSUES),
    ).fetchall()
    return {
        "document_issue_count": issue_count,
        "document_issues": [
            {
                "scope_id": str(row["scope_id"]),
                "relative_path": str(row["relative_path"]),
                "document_status": str(row["status"]),
                "needs_ocr": bool(row["needs_ocr"]),
                "limitations": _decode_limitations(str(row["limitations_json"])),
                "chunk_count": int(row["chunk_count"]),
            }
            for row in rows
        ],
        "document_issues_truncated": issue_count > len(rows),
    }


def _resolve_scope_root(root: Path, scope: Scope) -> Path:
    if scope.relative_dir == ".":
        return root
    relative = Path(scope.relative_dir)
    if (
        relative.is_absolute()
        or scope.relative_dir != relative.as_posix()
        or any(part in {"", ".", ".."} for part in relative.parts)
    ):
        raise ArchiveError(
            "Configured archive scope is not a normalized relative path."
        )
    candidate = root
    for part in relative.parts:
        candidate /= part
        if candidate.is_symlink():
            raise ArchiveError("Configured archive scope contains a symbolic link.")
    try:
        resolved = candidate.resolve(strict=True)
    except OSError as exc:
        raise ArchiveError(f"Configured archive scope is unavailable: {exc}") from exc
    if not _path_is_within(resolved, root) or not resolved.is_dir():
        raise ArchiveError("Configured archive scope escapes the archive root.")
    return resolved


def _walk_archive_entries(directory: Path) -> Iterator[tuple[Path, str | None]]:
    try:
        entries = sorted(
            os.scandir(directory),
            key=lambda entry: entry.name.casefold(),
        )
    except OSError as exc:
        raise ArchiveError(
            f"Archive enumeration failed at {directory.name}: {exc}"
        ) from exc
    for entry in entries:
        if entry.name in IGNORED_NAMES:
            continue
        try:
            if entry.is_symlink():
                yield Path(entry.path), "symbolic_link_not_followed"
            elif entry.is_dir(follow_symlinks=False):
                yield from _walk_archive_entries(Path(entry.path))
            elif entry.is_file(follow_symlinks=False):
                yield Path(entry.path), None
        except OSError as exc:
            raise ArchiveError(
                f"Archive enumeration failed at {entry.name}: {exc}"
            ) from exc


def _scope_entries(
    scope_root: Path,
    scope: Scope,
) -> Iterator[tuple[Path, str | None]]:
    """Yield source files for one non-overlapping configured scope."""

    if scope.relative_dir != ".":
        yield from _walk_archive_entries(scope_root)
        return
    try:
        entries = sorted(scope_root.iterdir(), key=lambda path: path.name.casefold())
    except OSError as exc:
        raise ArchiveError(f"Archive enumeration failed at root: {exc}") from exc
    for path in entries:
        if path.name in IGNORED_NAMES:
            continue
        if path.is_symlink():
            yield path, "symbolic_link_not_followed"
            continue
        try:
            if stat.S_ISREG(path.lstat().st_mode):
                yield path, None
        except OSError as exc:
            raise ArchiveError(
                f"Archive enumeration failed at {path.name}: {exc}"
            ) from exc


def _excluded_ledger_search_path(path: Path, scope_root: Path) -> bool:
    """Exclude technical manifests/runs while retaining canonical input evidence."""

    try:
        parts = path.relative_to(scope_root).parts
    except ValueError:
        return False
    if len(parts) == 1 and (
        parts[0]
        in {".pending-work.lock", ".project-layout.lock", "pending-archive-work.json"}
        or re.fullmatch(r"pending-(?:work|publication)-[0-9a-f]{64}\.json", parts[0])
    ):
        # These are reserved work-folder records, not client source evidence.
        # Outside an actual ledger, identically named user files stay searchable.
        try:
            ledger.load_client_manifest(scope_root)
        except (OSError, ValueError, ledger.LedgerError):
            return False
        return True
    if not parts or parts[0].casefold() not in ledger.PRODUCT_DIRECTORIES:
        return False
    if (
        len(parts) >= 6
        and parts[1] == "engagements"
        and re.fullmatch(r"eng_[0-9a-f]{24}", parts[2]) is not None
        and parts[3] == "inputs"
        and re.fullmatch(r"input_[0-9a-f]{24}", parts[4]) is not None
    ):
        return parts[5] == "receipt.json" or len(parts) != 6
    return True


def _discover_files(
    config: ArchiveConfig,
) -> tuple[list[DiscoveredFile], list[ScanIssue]]:
    discovered: list[DiscoveredFile] = []
    issues: list[ScanIssue] = []
    total_bytes = 0
    scanned_files = 0
    seen_paths: set[str] = set()
    seen_casefolded_paths: set[str] = set()
    for scope in config.scopes:
        scope_root = _resolve_scope_root(config.archive_root, scope)
        for path, skip_reason in _scope_entries(scope_root, scope):
            if _excluded_ledger_search_path(path, scope_root):
                continue
            relative_path = path.relative_to(config.archive_root).as_posix()
            if relative_path in seen_paths:
                raise ArchiveError(
                    f"Configured scopes overlap at archive path: {relative_path}"
                )
            seen_paths.add(relative_path)
            scanned_files += 1
            if scanned_files > MAX_FILES:
                raise ArchiveError(
                    f"Archive exceeds the {MAX_FILES:,}-file first-version limit."
                )
            if skip_reason is not None:
                issues.append(
                    ScanIssue(
                        scope_id=scope.scope_id,
                        relative_path=relative_path,
                        reason=skip_reason,
                        size_bytes=None,
                    )
                )
                continue
            try:
                metadata = path.lstat()
            except OSError:
                issues.append(
                    ScanIssue(
                        scope_id=scope.scope_id,
                        relative_path=relative_path,
                        reason="source_metadata_unavailable",
                        size_bytes=None,
                    )
                )
                continue
            if not stat.S_ISREG(metadata.st_mode):
                continue
            suffix = path.suffix.lower()
            if suffix not in SUPPORTED_SUFFIXES:
                issues.append(
                    ScanIssue(
                        scope_id=scope.scope_id,
                        relative_path=relative_path,
                        reason="unsupported_extension",
                        size_bytes=metadata.st_size,
                    )
                )
                continue
            casefolded_path = relative_path.casefold()
            if casefolded_path in seen_casefolded_paths:
                raise ArchiveError(
                    "Archive contains paths that collide when case is ignored: "
                    f"{relative_path}"
                )
            seen_casefolded_paths.add(casefolded_path)
            if metadata.st_size > MAX_FILE_BYTES:
                issues.append(
                    ScanIssue(
                        scope_id=scope.scope_id,
                        relative_path=relative_path,
                        reason="file_size_limit_exceeded",
                        size_bytes=metadata.st_size,
                    )
                )
                continue
            total_bytes += metadata.st_size
            if total_bytes > MAX_TOTAL_BYTES:
                raise ArchiveError(
                    "Archive exceeds the first-version total byte limit."
                )
            discovered.append(
                DiscoveredFile(
                    scope_id=scope.scope_id,
                    relative_path=relative_path,
                    path=path,
                    size_bytes=metadata.st_size,
                    mtime_ns=metadata.st_mtime_ns,
                )
            )
    return discovered, issues


def _resolve_source_file(
    root: Path, relative_path: str, *, project_relative: bool = False
) -> Path:
    """Resolve one indexed regular file without following symbolic links."""

    relative = Path(relative_path)
    if (
        relative.is_absolute()
        or relative_path != relative.as_posix()
        or any(part in {"", ".", ".."} for part in relative.parts)
    ):
        raise ArchiveError("Indexed source path is not normalized and relative.")
    candidate = root
    product_index = 0 if project_relative else 1
    for index, part in enumerate(relative.parts):
        if index == product_index and part.casefold() in ledger.PRODUCT_DIRECTORIES:
            candidate = ledger._product_root(candidate, part)
        else:
            candidate /= part
        if candidate.is_symlink():
            raise ArchiveError("Indexed source path contains a symbolic link.")
    try:
        resolved = candidate.resolve(strict=True)
    except OSError as exc:
        raise SourceChangedError(f"Indexed source is unavailable: {exc}") from exc
    if not _path_is_within(resolved, root):
        raise ArchiveError("Indexed source path escapes the archive root.")
    if not stat.S_ISREG(resolved.lstat().st_mode):
        raise ArchiveError("Indexed source is not a regular file.")
    return resolved


def _normalize_text(text: str) -> str:
    text = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]", " ", text)
    lines = [
        re.sub(r"[ \t]+", " ", line).strip()
        for line in text.replace("\r", "\n").split("\n")
    ]
    return "\n".join(line for line in lines if line).strip()


def _text_is_useful(text: str) -> bool:
    compact = _normalize_text(text)
    if len(compact) < 40:
        return False
    alpha_count = sum(character.isalpha() for character in compact)
    return alpha_count >= max(20, len(compact) // 10)


def _chunks_from_numbered_lines(
    rows: Sequence[tuple[int, str]],
    *,
    locator_kind: str,
    locator_prefix: str = "",
) -> tuple[ExtractedChunk, ...]:
    chunks: list[ExtractedChunk] = []
    current: list[tuple[int, str]] = []
    current_chars = 0

    def flush() -> None:
        nonlocal current, current_chars
        if not current:
            return
        start = current[0][0]
        end = current[-1][0]
        range_value = str(start) if start == end else f"{start}-{end}"
        locator_value = f"{locator_prefix}{range_value}"
        chunks.append(
            ExtractedChunk(
                ordinal=len(chunks),
                locator_kind=locator_kind,
                locator_value=locator_value,
                text="\n".join(value for _, value in current),
            )
        )
        current = []
        current_chars = 0

    for number, raw_text in rows:
        text = _normalize_text(raw_text)
        if not text:
            continue
        if current and (
            len(current) >= MAX_CHUNK_LINES
            or current_chars + len(text) + 1 > MAX_CHUNK_CHARS
        ):
            flush()
        if len(text) > MAX_CHUNK_CHARS:
            flush()
            for offset in range(0, len(text), MAX_CHUNK_CHARS):
                piece = text[offset : offset + MAX_CHUNK_CHARS]
                chunks.append(
                    ExtractedChunk(
                        ordinal=len(chunks),
                        locator_kind=locator_kind,
                        locator_value=f"{locator_prefix}{number}",
                        text=piece,
                    )
                )
            continue
        current.append((number, text))
        current_chars += len(text) + 1
    flush()
    return tuple(chunks)


def _extract_plain_text(path: Path) -> ExtractionResult:
    if path.stat().st_size > MAX_TEXT_BYTES:
        return ExtractionResult((), "text", "error", False, ("text_file_too_large",))
    payload = path.read_bytes()
    text = payload.decode("utf-8-sig", errors="replace")
    rows = tuple(enumerate(text.splitlines(), start=1))
    chunks = _chunks_from_numbered_lines(rows, locator_kind="lines")
    status = "indexed" if chunks else "partial"
    limitations = () if chunks else ("no_extractable_text",)
    return ExtractionResult(chunks, "plain_text", status, False, limitations)


def _validate_ooxml_archive(path: Path) -> None:
    with zipfile.ZipFile(path) as archive:
        members = [info for info in archive.infolist() if not info.is_dir()]
        if len(members) > MAX_OOXML_MEMBERS:
            raise ArchiveError("OOXML archive contains too many members.")
        names = [info.filename for info in members]
        if len(names) != len(set(names)):
            raise ArchiveError("OOXML archive contains duplicate member names.")
        if sum(info.file_size for info in members) > MAX_OOXML_TOTAL_BYTES:
            raise ArchiveError("Expanded OOXML archive exceeds the size limit.")
        for info in members:
            if info.flag_bits & 0x1:
                raise ArchiveError("Encrypted OOXML members are unsupported.")
            ratio = info.file_size / max(info.compress_size, 1)
            if info.file_size > MAX_OOXML_MEMBER_BYTES:
                raise ArchiveError("OOXML member exceeds the size limit.")
            if ratio > MAX_OOXML_COMPRESSION_RATIO:
                raise ArchiveError("OOXML member compression ratio is unsafe.")


def _extract_docx(path: Path) -> ExtractionResult:
    _validate_ooxml_archive(path)
    from docx import Document

    document = Document(path)
    chunks: list[ExtractedChunk] = list(
        _chunks_from_numbered_lines(
            tuple(
                (index, paragraph.text)
                for index, paragraph in enumerate(document.paragraphs, start=1)
            ),
            locator_kind="paragraphs",
        )
    )
    for table_number, table in enumerate(document.tables, start=1):
        rows = [
            "\t".join(_normalize_text(cell.text) for cell in row.cells)
            for row in table.rows
        ]
        for chunk in _chunks_from_numbered_lines(
            tuple(enumerate(rows, start=1)),
            locator_kind="table",
            locator_prefix=f"{table_number}, rows ",
        ):
            chunks.append(
                ExtractedChunk(
                    ordinal=len(chunks),
                    locator_kind=chunk.locator_kind,
                    locator_value=chunk.locator_value,
                    text=chunk.text,
                )
            )
    status = "indexed" if chunks else "partial"
    return ExtractionResult(
        tuple(chunks),
        "docx",
        status,
        False,
        () if chunks else ("no_extractable_text",),
    )


def _cell_text(value: Any) -> str:
    if value is None:
        return ""
    return _normalize_text(str(value))


def _extract_xlsx(path: Path) -> ExtractionResult:
    _validate_ooxml_archive(path)
    from openpyxl import load_workbook
    from openpyxl.utils import get_column_letter

    workbook = load_workbook(path, read_only=True, data_only=False)
    chunks: list[ExtractedChunk] = []
    limitations: list[str] = []
    try:
        for sheet_index, worksheet in enumerate(workbook.worksheets, start=1):
            if sheet_index > MAX_WORKBOOK_SHEETS:
                limitations.append("workbook_sheet_limit_reached")
                break
            rows: list[tuple[int, str]] = []
            if int(worksheet.max_column or 0) > MAX_WORKSHEET_COLUMNS:
                limitations.append(f"worksheet_column_limit_reached:{worksheet.title}")
            for row_number, row in enumerate(
                worksheet.iter_rows(max_col=MAX_WORKSHEET_COLUMNS),
                start=1,
            ):
                if row_number > MAX_WORKSHEET_ROWS:
                    limitations.append(f"worksheet_row_limit_reached:{worksheet.title}")
                    break
                values = []
                for column_number, cell in enumerate(row, start=1):
                    value = _cell_text(cell.value)
                    if value:
                        values.append(
                            f"{get_column_letter(column_number)}{row_number}={value}"
                        )
                if values:
                    rows.append((row_number, "\t".join(values)))
            for chunk in _chunks_from_numbered_lines(
                rows,
                locator_kind="sheet",
                locator_prefix=f"{worksheet.title}!rows ",
            ):
                chunks.append(
                    ExtractedChunk(
                        ordinal=len(chunks),
                        locator_kind=chunk.locator_kind,
                        locator_value=chunk.locator_value,
                        text=chunk.text,
                    )
                )
    finally:
        workbook.close()
    status = "indexed" if chunks and not limitations else "partial"
    if not chunks:
        limitations.append("no_extractable_text")
    return ExtractionResult(
        tuple(chunks),
        "xlsx",
        status,
        False,
        tuple(dict.fromkeys(limitations)),
    )


def _html_to_text(value: str) -> str:
    parser = _HtmlTextExtractor()
    parser.feed(value)
    parser.close()
    return " ".join(parser.parts)


def _extract_eml(path: Path) -> ExtractionResult:
    if path.stat().st_size > MAX_EMAIL_BYTES:
        return ExtractionResult((), "eml", "error", False, ("email_too_large",))
    message = BytesParser(policy=policy.default).parsebytes(path.read_bytes())
    lines = [
        f"Subject: {message.get('subject', '')}",
        f"From: {message.get('from', '')}",
        f"To: {message.get('to', '')}",
        f"Date: {message.get('date', '')}",
    ]
    attachment_count = 0
    for part in message.walk():
        if part.is_multipart():
            continue
        if part.get_content_disposition() == "attachment" or part.get_filename():
            attachment_count += 1
            continue
        if part.get_content_type() not in {"text/plain", "text/html"}:
            continue
        try:
            content = part.get_content()
        except (LookupError, UnicodeError):
            content = (part.get_payload(decode=True) or b"").decode(
                "utf-8",
                errors="replace",
            )
        text = content if isinstance(content, str) else str(content)
        if part.get_content_type() == "text/html":
            text = _html_to_text(text)
        lines.extend(text.splitlines())
    chunks = _chunks_from_numbered_lines(
        tuple(enumerate(lines, start=1)),
        locator_kind="message lines",
    )
    limitations = (
        (f"attachments_not_indexed:{attachment_count}",) if attachment_count else ()
    )
    status = "indexed" if chunks and not limitations else "partial"
    if not chunks:
        limitations = (*limitations, "no_extractable_text")
    return ExtractionResult(chunks, "eml", status, False, limitations)


def _ensure_vendor_import_path() -> None:
    component_root = Path(__file__).resolve().parents[1]
    candidates = (
        component_root / "vendor" / "modules",
        component_root.parent / "_shared" / "vendor" / "modules",
    )
    for candidate in candidates:
        if candidate.is_dir() and str(candidate) not in sys.path:
            sys.path.insert(0, str(candidate))


def _run_local_ocr(
    image_bytes: bytes, *, language: str = "it"
) -> tuple[str, tuple[str, ...], bool]:
    _ensure_vendor_import_path()
    try:
        from vera_ocr import extract_text_from_image_bytes
    except (ImportError, ModuleNotFoundError):
        return "", ("ocr_runtime_unavailable",), False
    result = extract_text_from_image_bytes(
        image_bytes,
        language=language,
        allow_model_download=False,
    )
    if result.network_used:
        raise ArchiveError("Local OCR unexpectedly reported network use.")
    warnings = tuple(str(value) for value in result.warnings)
    if result.status != "ok":
        return "", (f"ocr_{result.status}", *warnings), False
    return _normalize_text(result.text), warnings, True


def _render_pdf_page(path: Path, page_index: int) -> bytes:
    import fitz

    with fitz.open(path) as document:
        page = document.load_page(page_index)
        scale = 200.0 / 72.0
        rendered_pixels = int(page.rect.width * scale) * int(page.rect.height * scale)
        if rendered_pixels > MAX_IMAGE_TOTAL_PIXELS:
            raise ArchiveError("Rendered PDF page exceeds the OCR pixel limit.")
        pixmap = page.get_pixmap(matrix=fitz.Matrix(scale, scale))
        return bytes(pixmap.tobytes("png"))


def _page_chunks(
    text: str,
    *,
    page_number: int,
    ordinal_start: int,
) -> tuple[ExtractedChunk, ...]:
    normalized = _normalize_text(text)
    if not normalized:
        return ()
    pieces = [
        normalized[offset : offset + MAX_CHUNK_CHARS]
        for offset in range(0, len(normalized), MAX_CHUNK_CHARS)
    ]
    return tuple(
        ExtractedChunk(
            ordinal=ordinal_start + index,
            locator_kind="page",
            locator_value=str(page_number),
            text=piece,
        )
        for index, piece in enumerate(pieces)
    )


def _extract_pdf(
    path: Path, *, enable_ocr: bool, ocr_language: str = "it"
) -> ExtractionResult:
    if path.stat().st_size > MAX_PDF_BYTES:
        return ExtractionResult((), "pdf", "error", False, ("pdf_too_large",))
    from pypdf import PdfReader
    from pypdf.errors import PyPdfError

    try:
        reader = PdfReader(str(path))
        if reader.is_encrypted and not reader.decrypt(""):
            return ExtractionResult(
                (),
                "pdf",
                "partial",
                False,
                ("password_protected_pdf",),
            )
        total_pages = len(reader.pages)
    except (OSError, PyPdfError, RecursionError, TypeError, ValueError) as exc:
        return ExtractionResult(
            (),
            "pdf",
            "error",
            False,
            (f"pdf_open_failed:{type(exc).__name__}:{exc}",),
        )
    chunks: list[ExtractedChunk] = []
    limitations: list[str] = []
    needs_ocr = False
    used_ocr = False
    unresolved_ocr = False
    extracted_chars = 0
    page_limit = min(total_pages, MAX_PDF_PAGES)
    for page_index in range(page_limit):
        page_number = page_index + 1
        if extracted_chars >= MAX_PDF_TEXT_CHARS:
            limitations.append("pdf_text_character_limit_reached")
            break
        try:
            page = reader.pages[page_index]
            text = page.extract_text() or ""
        except (
            AttributeError,
            KeyError,
            PyPdfError,
            RecursionError,
            TypeError,
            ValueError,
        ):
            text = ""
            limitations.append(f"page_{page_number}_text_extraction_failed")
        if not _text_is_useful(text):
            needs_ocr = True
            native_text = _normalize_text(text)
            if enable_ocr:
                try:
                    image_bytes = _render_pdf_page(path, page_index)
                except (
                    ArchiveError,
                    ImportError,
                    ModuleNotFoundError,
                    OSError,
                    RuntimeError,
                    ValueError,
                ):
                    limitations.append(f"page_{page_number}_ocr_render_unavailable")
                else:
                    ocr_text, warnings, succeeded = _run_local_ocr(
                        image_bytes, language=ocr_language
                    )
                    limitations.extend(
                        f"page_{page_number}_{warning}" for warning in warnings
                    )
                    if succeeded and ocr_text:
                        text_parts = [native_text] if native_text else []
                        if ocr_text.casefold() not in native_text.casefold():
                            text_parts.append(ocr_text)
                        text = "\n".join(text_parts)
                        used_ocr = True
                        limitations.append(
                            f"page_{page_number}_ocr_text_requires_visual_confirmation"
                        )
            if not _text_is_useful(text):
                unresolved_ocr = True
                limitations.append(f"page_{page_number}_no_extractable_text")
        remaining_chars = MAX_PDF_TEXT_CHARS - extracted_chars
        if len(text) > remaining_chars:
            text = text[:remaining_chars]
            limitations.append("pdf_text_character_limit_reached")
        extracted_chars += len(text)
        chunks.extend(
            _page_chunks(
                text,
                page_number=page_number,
                ordinal_start=len(chunks),
            )
        )
    if total_pages > MAX_PDF_PAGES:
        limitations.append(f"pdf_page_limit_reached:{MAX_PDF_PAGES}/{total_pages}")
    method = "pdf_text+local_ocr" if used_ocr else "pdf_text"
    if not chunks:
        status = "partial"
    elif limitations:
        status = "partial"
    else:
        status = "indexed"
    return ExtractionResult(
        tuple(chunks),
        method,
        status,
        needs_ocr and unresolved_ocr,
        tuple(dict.fromkeys(limitations)),
    )


def _image_frames(path: Path) -> tuple[tuple[bytes, ...], bool]:
    from PIL import Image

    frames: list[bytes] = []
    total_pixels = 0
    try:
        with warnings.catch_warnings():
            warnings.simplefilter("error", Image.DecompressionBombWarning)
            with Image.open(path) as image:
                source_frame_count = max(
                    1,
                    int(getattr(image, "n_frames", 1)),
                )
                frame_count = min(
                    source_frame_count,
                    MAX_IMAGE_FRAMES,
                )
                for frame_index in range(frame_count):
                    image.seek(frame_index)
                    frame_pixels = int(image.width) * int(image.height)
                    total_pixels += frame_pixels
                    if total_pixels > MAX_IMAGE_TOTAL_PIXELS:
                        raise ArchiveError("Image frames exceed the OCR pixel limit.")
                    frame = image.convert("RGB")
                    buffer = io.BytesIO()
                    frame.save(buffer, format="PNG")
                    frames.append(buffer.getvalue())
    except (Image.DecompressionBombError, Image.DecompressionBombWarning) as exc:
        raise ArchiveError("Image exceeds the safe decoding limit.") from exc
    return tuple(frames), source_frame_count > MAX_IMAGE_FRAMES


def _extract_image(
    path: Path, *, enable_ocr: bool, ocr_language: str = "it"
) -> ExtractionResult:
    if not enable_ocr:
        return ExtractionResult((), "image", "partial", True, ("ocr_disabled",))
    chunks: list[ExtractedChunk] = []
    limitations: list[str] = []
    unresolved_ocr = False
    try:
        frames, frames_truncated = _image_frames(path)
    except (ArchiveError, ImportError, ModuleNotFoundError, OSError, ValueError):
        return ExtractionResult(
            (),
            "image",
            "partial",
            True,
            ("image_frame_extraction_failed",),
        )
    if frames_truncated:
        limitations.append(f"image_frame_limit_reached:{MAX_IMAGE_FRAMES}")
    for page_number, image_bytes in enumerate(frames, start=1):
        text, warnings, succeeded = _run_local_ocr(image_bytes, language=ocr_language)
        limitations.extend(f"page_{page_number}_{warning}" for warning in warnings)
        if succeeded and text:
            limitations.append(
                f"page_{page_number}_ocr_text_requires_visual_confirmation"
            )
        else:
            unresolved_ocr = True
            limitations.append(f"page_{page_number}_no_extractable_text")
        chunks.extend(
            _page_chunks(
                text,
                page_number=page_number,
                ordinal_start=len(chunks),
            )
        )
    status = "indexed" if chunks and not limitations else "partial"
    return ExtractionResult(
        tuple(chunks),
        "local_ocr",
        status,
        unresolved_ocr or not bool(chunks),
        tuple(dict.fromkeys(limitations)),
    )


def _extract_document(
    path: Path, *, enable_ocr: bool, ocr_language: str = "it"
) -> ExtractionResult:
    suffix = path.suffix.lower()
    try:
        if suffix in TEXT_SUFFIXES:
            return _extract_plain_text(path)
        if suffix in PDF_SUFFIXES:
            return _extract_pdf(path, enable_ocr=enable_ocr, ocr_language=ocr_language)
        if suffix in DOCX_SUFFIXES:
            return _extract_docx(path)
        if suffix in XLSX_SUFFIXES:
            return _extract_xlsx(path)
        if suffix in EMAIL_SUFFIXES:
            return _extract_eml(path)
        if suffix in IMAGE_SUFFIXES:
            return _extract_image(
                path, enable_ocr=enable_ocr, ocr_language=ocr_language
            )
    except (
        ArchiveError,
        AttributeError,
        ImportError,
        KeyError,
        ModuleNotFoundError,
        NotImplementedError,
        OSError,
        RecursionError,
        RuntimeError,
        SyntaxError,  # Includes XML parser errors from supported Office readers.
        TypeError,
        UnicodeError,
        ValueError,
        zipfile.BadZipFile,
        zipfile.LargeZipFile,
    ) as exc:
        return ExtractionResult(
            (),
            suffix.removeprefix(".") or "unknown",
            "error",
            suffix in IMAGE_SUFFIXES,
            (f"extraction_failed:{type(exc).__name__}:{exc}",),
        )
    return ExtractionResult((), "unsupported", "error", False, ("unsupported",))


def _delete_document_chunks(
    connection: sqlite3.Connection,
    document_id: str,
) -> None:
    source_rows = connection.execute(
        "SELECT source_id FROM chunks WHERE document_id = ?",
        (document_id,),
    ).fetchall()
    source_ids = [str(row["source_id"]) for row in source_rows]
    if source_ids:
        connection.executemany(
            "DELETE FROM chunk_fts WHERE source_id = ?",
            ((source_id,) for source_id in source_ids),
        )
    connection.execute(
        "DELETE FROM chunks WHERE document_id = ?",
        (document_id,),
    )


def _replace_document(
    connection: sqlite3.Connection,
    *,
    item: DiscoveredFile,
    source_sha256: str,
    extraction: ExtractionResult,
    generation: int,
    indexed_at: str,
) -> None:
    document_id = _stable_id("doc", item.relative_path.casefold())
    _delete_document_chunks(connection, document_id)
    connection.execute(
        """
        INSERT INTO documents(
            document_id, scope_id, relative_path, extension, size_bytes,
            mtime_ns, sha256, extraction_method, status, needs_ocr,
            limitations_json, indexed_at, last_seen_generation
        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(document_id) DO UPDATE SET
            scope_id = excluded.scope_id,
            relative_path = excluded.relative_path,
            extension = excluded.extension,
            size_bytes = excluded.size_bytes,
            mtime_ns = excluded.mtime_ns,
            sha256 = excluded.sha256,
            extraction_method = excluded.extraction_method,
            status = excluded.status,
            needs_ocr = excluded.needs_ocr,
            limitations_json = excluded.limitations_json,
            indexed_at = excluded.indexed_at,
            last_seen_generation = excluded.last_seen_generation
        """,
        (
            document_id,
            item.scope_id,
            item.relative_path,
            item.path.suffix.lower(),
            item.size_bytes,
            item.mtime_ns,
            source_sha256,
            extraction.extraction_method,
            extraction.status,
            int(extraction.needs_ocr),
            json.dumps(extraction.limitations, ensure_ascii=False),
            indexed_at,
            generation,
        ),
    )
    for chunk in extraction.chunks:
        text_sha256 = _sha256_bytes(chunk.text.encode("utf-8"))
        source_id = _stable_id(
            "src",
            document_id,
            source_sha256,
            chunk.locator_kind,
            chunk.locator_value,
            str(chunk.ordinal),
            text_sha256,
        )
        connection.execute(
            """
            INSERT INTO chunks(
                source_id, document_id, ordinal, locator_kind, locator_value,
                text, text_sha256
            ) VALUES (?, ?, ?, ?, ?, ?, ?)
            """,
            (
                source_id,
                document_id,
                chunk.ordinal,
                chunk.locator_kind,
                chunk.locator_value,
                chunk.text,
                text_sha256,
            ),
        )
        connection.execute(
            "INSERT INTO chunk_fts(source_id, text) VALUES (?, ?)",
            (source_id, chunk.text),
        )


def _index_refresh_transaction(function: Callable[..., Any]) -> Callable[..., Any]:
    """Serialize refresh writers across sessions using the same private index."""

    @wraps(function)
    def wrapped(*args: Any, **kwargs: Any) -> Any:
        state = _state_dir(kwargs.get("state_dir"))
        path = _database_path(state)
        with preferences.file_lock(
            path.parent / ".index-refresh.lock", label="search index"
        ):
            return function(*args, **kwargs)

    return wrapped


@_index_refresh_transaction
def refresh_archive(
    *,
    rebuild: bool = False,
    only_if_required: bool = False,
    enable_ocr: bool = False,
    ocr_language: str = "it",
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Incrementally refresh the private local index without writing source files."""

    if ocr_language not in {"it", "fr", "de", "en", "es"}:
        raise ArchiveError("Unsupported OCR language; choose it, fr, de, en or es.")

    private_state = _state_dir(state_dir)
    stored_config = _load_config(private_state, validate_scope_roots=False)
    current_scopes = _discover_top_level_scopes(stored_config.archive_root)
    scopes_changed = current_scopes != stored_config.scopes
    if scopes_changed:
        config = ArchiveConfig(
            archive_root=stored_config.archive_root,
            scopes=current_scopes,
            configured_at=_now_iso(),
        )
        _write_private_json(_config_path(private_state), config.as_json())
    else:
        config = stored_config
    # Reconcile this session before checking the shared index under its writer
    # lock, so another session's completed recovery is reused without extraction.
    if only_if_required and not rebuild:
        status = studio_archive_status(state_dir=private_state)
        if not status["index_requires_refresh"]:
            return {**status, "refreshed": False}
    discovered, scan_issues = _discover_files(config)
    connection = _connect(private_state)
    indexed_at = _now_iso()
    try:
        previous_generation = int(_metadata_get(connection, "scan_generation") or "0")
        generation = previous_generation + 1
        fingerprint = _config_fingerprint(config)
        ocr_language_changed = ocr_language != (
            _metadata_get(connection, "ocr_language") or "it"
        )
        indexed_root = _metadata_get(connection, "archive_root")
        root_changed = indexed_root is not None and indexed_root != str(
            config.archive_root
        )
        if rebuild or root_changed:
            _clear_index(connection)
        existing = {
            str(row["relative_path"]): row
            for row in connection.execute("SELECT * FROM documents").fetchall()
        }
        _replace_scan_issues(connection, scan_issues)
        counts = {
            "discovered_files": len(discovered),
            "indexed_files": 0,
            "unchanged_files": 0,
            "metadata_only_files": 0,
            "removed_files": 0,
            "partial_files": 0,
            "failed_files": 0,
            "needs_ocr_files": 0,
            "unsupported_files": sum(
                issue.reason == "unsupported_extension" for issue in scan_issues
            ),
            "oversized_files": sum(
                issue.reason == "file_size_limit_exceeded" for issue in scan_issues
            ),
        }
        for item in discovered:
            previous = existing.get(item.relative_path)
            requires_reindex = previous is not None and (
                str(previous["status"]) == "error"
                or (
                    enable_ocr and (bool(previous["needs_ocr"]) or ocr_language_changed)
                )
            )
            try:
                source_path = _resolve_source_file(
                    config.archive_root,
                    item.relative_path,
                )
                source_sha256 = _sha256_file(source_path)
            except (ArchiveError, OSError) as exc:
                extraction = ExtractionResult(
                    (),
                    item.path.suffix.lower().removeprefix(".") or "unknown",
                    "error",
                    item.path.suffix.lower() in IMAGE_SUFFIXES,
                    (f"source_unavailable_before_extraction:{exc}",),
                )
                _replace_document(
                    connection,
                    item=item,
                    source_sha256="",
                    extraction=extraction,
                    generation=generation,
                    indexed_at=indexed_at,
                )
                counts["indexed_files"] += 1
                counts["failed_files"] += 1
                counts["needs_ocr_files"] += int(extraction.needs_ocr)
                continue
            if (
                previous is not None
                and str(previous["sha256"]) == source_sha256
                and not requires_reindex
            ):
                connection.execute(
                    """
                    UPDATE documents
                    SET size_bytes = ?, mtime_ns = ?, last_seen_generation = ?
                    WHERE relative_path = ?
                    """,
                    (
                        item.size_bytes,
                        item.mtime_ns,
                        generation,
                        item.relative_path,
                    ),
                )
                metadata_unchanged = (
                    int(previous["size_bytes"]) == item.size_bytes
                    and int(previous["mtime_ns"]) == item.mtime_ns
                )
                count_key = (
                    "unchanged_files" if metadata_unchanged else "metadata_only_files"
                )
                counts[count_key] += 1
                counts["partial_files"] += int(previous["status"] == "partial")
                counts["failed_files"] += int(previous["status"] == "error")
                counts["needs_ocr_files"] += int(previous["needs_ocr"])
                continue

            extraction = _extract_document(
                source_path, enable_ocr=enable_ocr, ocr_language=ocr_language
            )
            try:
                post_metadata = source_path.lstat()
                post_sha256 = _sha256_file(source_path)
            except (ArchiveError, OSError) as exc:
                extraction = ExtractionResult(
                    (),
                    extraction.extraction_method,
                    "error",
                    extraction.needs_ocr,
                    (
                        *extraction.limitations,
                        f"source_unavailable_after_extraction:{exc}",
                    ),
                )
                post_metadata = None
                post_sha256 = ""
            if (
                post_metadata is None
                or post_metadata.st_size != item.size_bytes
                or post_metadata.st_mtime_ns != item.mtime_ns
                or post_sha256 != source_sha256
            ):
                extraction = ExtractionResult(
                    (),
                    extraction.extraction_method,
                    "error",
                    extraction.needs_ocr,
                    (*extraction.limitations, "source_changed_during_refresh"),
                )
            _replace_document(
                connection,
                item=item,
                source_sha256=source_sha256,
                extraction=extraction,
                generation=generation,
                indexed_at=indexed_at,
            )
            counts["indexed_files"] += 1
            counts["partial_files"] += int(extraction.status == "partial")
            counts["failed_files"] += int(extraction.status == "error")
            counts["needs_ocr_files"] += int(extraction.needs_ocr)

        removed_rows = connection.execute(
            """
            SELECT document_id FROM documents
            WHERE last_seen_generation != ?
            """,
            (generation,),
        ).fetchall()
        for row in removed_rows:
            document_id = str(row["document_id"])
            _delete_document_chunks(connection, document_id)
            connection.execute(
                "DELETE FROM documents WHERE document_id = ?",
                (document_id,),
            )
        counts["removed_files"] = len(removed_rows)
        _metadata_set(connection, "scan_generation", str(generation))
        _metadata_set(connection, "last_refresh_at", indexed_at)
        _metadata_set(connection, "config_fingerprint", fingerprint)
        _metadata_set(connection, "archive_root", str(config.archive_root))
        _metadata_set(connection, "ocr_enabled_last_refresh", json.dumps(enable_ocr))
        if enable_ocr:
            _metadata_set(connection, "ocr_language", ocr_language)
        connection.commit()
        document_count = int(
            connection.execute("SELECT COUNT(*) AS count FROM documents").fetchone()[
                "count"
            ]
        )
        chunk_count = int(
            connection.execute("SELECT COUNT(*) AS count FROM chunks").fetchone()[
                "count"
            ]
        )
        recovered_clients, identity_issues = _client_identity_view(
            private_state, config
        )
        return {
            "status": "refreshed",
            "last_refresh_at": indexed_at,
            "rebuild": bool(rebuild or root_changed),
            "scope_configuration_changed": scopes_changed,
            "identity_registry_complete": not identity_issues,
            "identity_issues": identity_issues,
            "scopes": _scope_records(config),
            "ocr_enabled": enable_ocr,
            "ocr_language": ocr_language,
            "document_count": document_count,
            "chunk_count": chunk_count,
            "recovered_client_count": len(
                [
                    record
                    for record in recovered_clients
                    if any(scope.scope_id == record.scope_id for scope in config.scopes)
                ]
            ),
            **counts,
            **_scan_issue_status(connection),
            **_document_issue_status(connection),
        }
    finally:
        connection.close()


def _scope_records(config: ArchiveConfig) -> list[dict[str, str]]:
    return [scope.as_json() for scope in config.scopes]


def _current_scope_view(config: ArchiveConfig) -> tuple[ArchiveConfig, bool]:
    issues: list[dict[str, Any]] = []
    try:
        current_scopes = _discover_top_level_scopes(config.archive_root, issues=issues)
    except ArchiveAccessError as exc:
        if exc.details["stage"] != "root_listing":
            raise
        # A known location is a routing hint, not authorization: selected
        # manifests and source receipts still validate on the actual filesystem.
        return (
            ArchiveConfig(
                config.archive_root,
                config.scopes,
                config.configured_at,
                directory_issue={
                    "issue_code": "scope_listing_unavailable",
                    "reason": str(exc),
                    "available": False,
                    "known_scopes_only": True,
                },
            ),
            False,
        )
    changed = current_scopes != config.scopes
    if (
        not changed
        and not issues
        and not config.scope_issues
        and config.directory_issue is None
    ):
        return config, False
    return (
        ArchiveConfig(
            archive_root=config.archive_root,
            scopes=current_scopes,
            configured_at=config.configured_at,
            scope_issues=tuple(issues),
        ),
        changed,
    )


def studio_archive_status(*, state_dir: Path | None = None) -> dict[str, Any]:
    """Return configuration and derived-index status without changing state."""

    private_state = _state_dir(state_dir)
    _restore_approved_root(private_state)
    config_path = _config_path(private_state)
    if not config_path.is_file():
        return {
            "configured": False,
            "document_count": 0,
            "chunk_count": 0,
            "last_refresh_at": None,
            "scopes": [],
            "needs_ocr_document_count": 0,
            "partial_document_count": 0,
            "failed_document_count": 0,
            "scan_issue_count": 0,
            "scan_issues": [],
            "scan_issues_truncated": False,
            "document_issue_count": 0,
            "document_issues": [],
            "document_issues_truncated": False,
            **_studio_archive_setup_contract(),
        }
    stored_config = _load_config(private_state, validate_scope_roots=False)
    config, scopes_changed = _current_scope_view(stored_config)
    database_path = _database_path(private_state)
    if not database_path.is_file():
        return {
            "configured": True,
            "archive_root": str(config.archive_root),
            "document_count": 0,
            "chunk_count": 0,
            "last_refresh_at": None,
            "scopes": _scope_records(config),
            "index_requires_refresh": True,
            "scope_configuration_changed": scopes_changed,
            "scope_discovery_complete": not config.scope_issues
            and config.directory_issue is None,
            "scope_discovery_issues": list(config.scope_issues)
            + ([config.directory_issue] if config.directory_issue else []),
            "needs_ocr_document_count": 0,
            "partial_document_count": 0,
            "failed_document_count": 0,
            "scan_issue_count": 0,
            "scan_issues": [],
            "scan_issues_truncated": False,
            "document_issue_count": 0,
            "document_issues": [],
            "document_issues_truncated": False,
        }
    connection = _connect(private_state, readonly=True)
    try:
        document_count = int(
            connection.execute("SELECT COUNT(*) AS count FROM documents").fetchone()[
                "count"
            ]
        )
        chunk_count = int(
            connection.execute("SELECT COUNT(*) AS count FROM chunks").fetchone()[
                "count"
            ]
        )
        fingerprint_matches = _metadata_get(
            connection, "config_fingerprint"
        ) == _config_fingerprint(stored_config)
        return {
            "configured": True,
            "archive_root": str(config.archive_root),
            "document_count": document_count,
            "chunk_count": chunk_count,
            "last_refresh_at": _metadata_get(connection, "last_refresh_at"),
            "scopes": _scope_records(config),
            "index_requires_refresh": scopes_changed or not fingerprint_matches,
            "scope_configuration_changed": scopes_changed,
            "scope_discovery_complete": not config.scope_issues
            and config.directory_issue is None,
            "scope_discovery_issues": list(config.scope_issues)
            + ([config.directory_issue] if config.directory_issue else []),
            "needs_ocr_document_count": int(
                connection.execute(
                    "SELECT COUNT(*) AS count FROM documents WHERE needs_ocr = 1"
                ).fetchone()["count"]
            ),
            "partial_document_count": int(
                connection.execute(
                    "SELECT COUNT(*) AS count FROM documents WHERE status = 'partial'"
                ).fetchone()["count"]
            ),
            "failed_document_count": int(
                connection.execute(
                    "SELECT COUNT(*) AS count FROM documents WHERE status = 'error'"
                ).fetchone()["count"]
            ),
            **_scan_issue_status(connection),
            **_document_issue_status(connection),
        }
    finally:
        connection.close()


def _fts_query(value: str) -> str:
    if not isinstance(value, str) or not value.strip():
        raise ArchiveError("Search query must be non-empty.")
    if len(value) > 500:
        raise ArchiveError("Search query must contain at most 500 characters.")
    tokens: list[str] = []
    seen: set[str] = set()
    for match in re.finditer(r"[^\W_]+", value, flags=re.UNICODE):
        token = match.group(0)
        key = token.casefold()
        if len(key) < 2 or key in seen:
            continue
        seen.add(key)
        tokens.append(token)
        if len(tokens) >= MAX_SEARCH_TOKENS:
            break
    if not tokens:
        raise ArchiveError("Search query contains no searchable terms.")
    return " OR ".join(f'"{token.replace(chr(34), chr(34) * 2)}"' for token in tokens)


def _citation(relative_path: str, locator_kind: str, locator_value: str) -> str:
    if locator_kind == "page":
        return f"{relative_path}, p. {locator_value}"
    return f"{relative_path}, {locator_kind} {locator_value}"


def _decode_limitations(value: str) -> list[str]:
    try:
        payload = json.loads(value)
    except json.JSONDecodeError:
        return ["invalid_stored_extraction_limitations"]
    if not isinstance(payload, list) or not all(
        isinstance(item, str) for item in payload
    ):
        return ["invalid_stored_extraction_limitations"]
    return payload


def _product_source_visible(relative_path: str) -> bool:
    """Shared source files stay available; another product's area does not."""
    parts = Path(relative_path).parts
    return not (
        len(parts) > 1
        and parts[1].casefold() in ledger.PRODUCT_DIRECTORIES
        and parts[1].casefold() != ledger.product_directory()
    )


def search_archive(
    query: str,
    *,
    scope_id: str,
    limit: int = 10,
    state_dir: Path | None = None,
    allowed_scope_ids: set[str] | None = None,
) -> dict[str, Any]:
    """Search one exact configured scope, or ``all`` when explicitly requested."""

    if not 1 <= int(limit) <= 20:
        raise ArchiveError("Search limit must be between 1 and 20.")
    private_state = _state_dir(state_dir)
    config = _load_config(private_state, validate_scope_roots=False)
    current, scopes_changed = _current_scope_view(config)
    unchanged_scopes = {
        scope.scope_id for scope in config.scopes if scope in current.scopes
    }
    # A new unrelated client does not invalidate an existing scoped index.
    # Global searches still require refresh so they cannot omit a new scope.
    if scopes_changed and (scope_id == "all" or scope_id not in unchanged_scopes):
        raise ArchiveError(
            "Top-level archive scopes changed; refresh before searching."
        )
    allowed_scopes = {scope.scope_id for scope in config.scopes}
    if scope_id != "all" and scope_id not in allowed_scopes:
        raise ArchiveError("Search scope is not configured.")
    expression = _fts_query(query)
    connection = _connect(private_state, readonly=True)
    connection.create_function("product_source_visible", 1, _product_source_visible)
    connection.create_function(
        "panel_scope_visible",
        1,
        lambda scope: allowed_scope_ids is None or scope in allowed_scope_ids,
    )
    try:
        if _metadata_get(connection, "config_fingerprint") != _config_fingerprint(
            config
        ):
            raise ArchiveError(
                "Archive configuration changed; refresh before searching."
            )
        # Deduplicate before LIMIT so one document with many high-scoring chunks
        # cannot mechanically hide other matching documents.
        if scope_id == "all":
            rows = connection.execute(
                """
                WITH matches AS (
                    SELECT
                        c.source_id,
                        c.document_id,
                        c.ordinal,
                        c.locator_kind,
                        c.locator_value,
                        d.scope_id,
                        d.relative_path,
                        d.sha256,
                        d.extraction_method,
                        d.status,
                        d.needs_ocr,
                        d.limitations_json,
                        d.indexed_at,
                        bm25(chunk_fts) AS score,
                        snippet(chunk_fts, 1, '[[', ']]', ' … ', 28) AS snippet
                    FROM chunk_fts
                    JOIN chunks AS c ON c.source_id = chunk_fts.source_id
                    JOIN documents AS d ON d.document_id = c.document_id
                    WHERE chunk_fts MATCH ?
                      AND product_source_visible(d.relative_path)
                      AND panel_scope_visible(d.scope_id)
                ), ranked AS (
                    SELECT
                        *,
                        ROW_NUMBER() OVER (
                            PARTITION BY scope_id, sha256
                            ORDER BY score, relative_path, ordinal
                        ) AS content_rank
                    FROM matches
                )
                SELECT *
                FROM ranked
                WHERE content_rank = 1
                ORDER BY score, relative_path, ordinal
                LIMIT ?
                """,
                (expression, int(limit)),
            ).fetchall()
        else:
            rows = connection.execute(
                """
                WITH matches AS (
                    SELECT
                        c.source_id,
                        c.document_id,
                        c.ordinal,
                        c.locator_kind,
                        c.locator_value,
                        d.scope_id,
                        d.relative_path,
                        d.sha256,
                        d.extraction_method,
                        d.status,
                        d.needs_ocr,
                        d.limitations_json,
                        d.indexed_at,
                        bm25(chunk_fts) AS score,
                        snippet(chunk_fts, 1, '[[', ']]', ' … ', 28) AS snippet
                    FROM chunk_fts
                    JOIN chunks AS c ON c.source_id = chunk_fts.source_id
                    JOIN documents AS d ON d.document_id = c.document_id
                    WHERE chunk_fts MATCH ?
                      AND product_source_visible(d.relative_path)
                      AND panel_scope_visible(d.scope_id)
                      AND d.scope_id = ?
                ), ranked AS (
                    SELECT
                        *,
                        ROW_NUMBER() OVER (
                            PARTITION BY scope_id, sha256
                            ORDER BY score, relative_path, ordinal
                        ) AS content_rank
                    FROM matches
                )
                SELECT *
                FROM ranked
                WHERE content_rank = 1
                ORDER BY score, relative_path, ordinal
                LIMIT ?
                """,
                (expression, scope_id, int(limit)),
            ).fetchall()
        results: list[dict[str, Any]] = []
        seen_documents: set[tuple[str, str]] = set()
        for row in rows:
            content_key = (str(row["scope_id"]), str(row["sha256"]))
            if content_key in seen_documents:
                continue
            seen_documents.add(content_key)
            results.append(
                {
                    "rank": len(results) + 1,
                    "source_id": str(row["source_id"]),
                    "document_id": str(row["document_id"]),
                    "scope_id": str(row["scope_id"]),
                    "relative_path": str(row["relative_path"]),
                    "locator_kind": str(row["locator_kind"]),
                    "locator_value": str(row["locator_value"]),
                    "citation": _citation(
                        str(row["relative_path"]),
                        str(row["locator_kind"]),
                        str(row["locator_value"]),
                    ),
                    "snippet": str(row["snippet"]),
                    "extraction_method": str(row["extraction_method"]),
                    "document_status": str(row["status"]),
                    "needs_ocr": bool(row["needs_ocr"]),
                    "limitations": _decode_limitations(str(row["limitations_json"])),
                    "source_sha256": str(row["sha256"]),
                    "indexed_at": str(row["indexed_at"]),
                    "score": float(row["score"]),
                    "verification_required": True,
                }
            )
            if len(results) == int(limit):
                break
        return {
            "query": query,
            "scope_id": scope_id,
            "scope_configuration_changed": scopes_changed,
            "index_requires_refresh": scopes_changed,
            "result_count": len(results),
            "results": results,
            **_scan_issue_status(
                connection,
                scope_id=None if scope_id == "all" else scope_id,
            ),
            **_document_issue_status(
                connection,
                scope_id=None if scope_id == "all" else scope_id,
            ),
        }
    finally:
        connection.close()


def open_archive_source(
    source_id: str,
    *,
    context_chunks: int = 0,
    state_dir: Path | None = None,
) -> dict[str, Any]:
    """Open one indexed source ID after re-verifying the current source bytes."""

    if not isinstance(source_id, str) or not re.fullmatch(
        r"src_[0-9a-f]{24}", source_id
    ):
        raise ArchiveError("Source ID is invalid.")
    if not 0 <= int(context_chunks) <= 2:
        raise ArchiveError("context_chunks must be between 0 and 2.")
    private_state = _state_dir(state_dir)
    config = _load_config(private_state, validate_scope_roots=False)
    current, scopes_changed = _current_scope_view(config)
    connection = _connect(private_state, readonly=True)
    try:
        if _metadata_get(connection, "config_fingerprint") != _config_fingerprint(
            config
        ):
            raise ArchiveError(
                "Archive configuration changed; refresh before opening sources."
            )
        row = connection.execute(
            """
            SELECT c.*, d.relative_path, d.sha256, d.scope_id,
                   d.extraction_method, d.status, d.needs_ocr,
                   d.limitations_json, d.indexed_at
            FROM chunks AS c
            JOIN documents AS d ON d.document_id = c.document_id
            WHERE c.source_id = ?
            """,
            (source_id,),
        ).fetchone()
        if row is None:
            raise ArchiveError("Source ID is not present in the current index.")
        if not _product_source_visible(str(row["relative_path"])):
            raise ArchiveError("Source belongs to another product.")
        if scopes_changed and not any(
            scope.scope_id == row["scope_id"] and scope in current.scopes
            for scope in config.scopes
        ):
            raise ArchiveError(
                "Selected archive scope changed; refresh before opening sources."
            )
        source_path = _resolve_source_file(
            config.archive_root, str(row["relative_path"])
        )
        current_sha256 = _sha256_file(source_path)
        if current_sha256 != str(row["sha256"]):
            raise SourceChangedError(
                "The source file changed after indexing. Refresh before using this "
                "citation; rebuild if the ordinary refresh still reports it as stale."
            )
        context = int(context_chunks)
        context_rows = connection.execute(
            """
            SELECT source_id, ordinal, locator_kind, locator_value, text
            FROM chunks
            WHERE document_id = ? AND ordinal BETWEEN ? AND ?
            ORDER BY ordinal
            """,
            (
                str(row["document_id"]),
                max(0, int(row["ordinal"]) - context),
                int(row["ordinal"]) + context,
            ),
        ).fetchall()
        fragments = [
            {
                "source_id": str(context_row["source_id"]),
                "ordinal": int(context_row["ordinal"]),
                "locator_kind": str(context_row["locator_kind"]),
                "locator_value": str(context_row["locator_value"]),
                "citation": _citation(
                    str(row["relative_path"]),
                    str(context_row["locator_kind"]),
                    str(context_row["locator_value"]),
                ),
                "text": str(context_row["text"])[:MAX_OPEN_CHARS],
            }
            for context_row in context_rows
        ]
        return {
            "source_id": source_id,
            "document_id": str(row["document_id"]),
            "scope_id": str(row["scope_id"]),
            "relative_path": str(row["relative_path"]),
            "locator_kind": str(row["locator_kind"]),
            "locator_value": str(row["locator_value"]),
            "citation": _citation(
                str(row["relative_path"]),
                str(row["locator_kind"]),
                str(row["locator_value"]),
            ),
            "source_sha256": str(row["sha256"]),
            "source_verified": True,
            "scope_configuration_changed": scopes_changed,
            "index_requires_refresh": scopes_changed,
            "extraction_method": str(row["extraction_method"]),
            "document_status": str(row["status"]),
            "needs_ocr": bool(row["needs_ocr"]),
            "limitations": _decode_limitations(str(row["limitations_json"])),
            "indexed_at": str(row["indexed_at"]),
            "fragments": fragments,
            **_scan_issue_status(connection, scope_id=str(row["scope_id"])),
            **_document_issue_status(connection, scope_id=str(row["scope_id"])),
        }
    finally:
        connection.close()


def _verify_run_configuration(function: Callable[..., Any]) -> Callable[..., Any]:
    """Serialize each session operation, including nested calls, and release it."""

    @wraps(function)
    def checked(*args: Any, **kwargs: Any) -> Any:
        state = (
            _state_dir(args[0])
            if function.__name__ == "_load_config"
            else _state_location(kwargs.get("state_dir"))
        )
        with _STATE_MUTEX_GUARD:
            mutex = _STATE_MUTEXES.setdefault(state, RLock())
        with mutex:
            depth = _STATE_DEPTH.get(state, 0)
            _STATE_DEPTH[state] = depth + 1
            try:
                result = function(*args, **kwargs)
                if state in _STATE_LEASES:
                    _check_configuration(state)
                return result
            finally:
                if depth:
                    _STATE_DEPTH[state] = depth
                else:
                    _STATE_DEPTH.pop(state, None)
                    _release_state_lease(state)

    return checked


for _operation_name in __all__:
    _operation = globals()[_operation_name]
    if (
        callable(_operation)
        and not isinstance(_operation, type)
        and _operation_name != "check_studio_import_sources"
    ):
        globals()[_operation_name] = _verify_run_configuration(_operation)

_load_config = _verify_run_configuration(_load_config)

SHA-256: e1f5bfc2162f231e2c36de38f0d7f2bf2364e87185a427d8f41acd191f782d31