Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

54.9 KB
Raw Blame
"""Current paired-instance Permissions client and offline projection cache."""

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime, timezone
import json
import logging
from pathlib import Path
import threading
import time
from typing import Any, Callable, Mapping, NoReturn
from urllib.parse import quote, urlsplit

import requests

from config import paths
from config.atomic_io import write_atomic
from config.v2_config import V2Config, config_file_lock

from sqlalchemy import select
from sqlalchemy.engine import Connection

from storage.db import get_cached_sqlite_engine
from storage.models import state_meta


CACHE_SCHEMA_VERSION = 1
CACHE_FILENAME = "permissions_projection.json"
CACHE_ORDER_FILENAME = "permissions_projection.order"
DEFAULT_TIMEOUT_SECONDS = 8.0
_SENSITIVE_KEY_PARTS = ("secret", "token", "credential")
_CACHE_FALLBACK_HTTP_STATUSES = frozenset({408, 425, 429})
_ACCESS_MODES = frozenset({"allowlist", "public"})
_PERMISSION_AUTHORITIES = frozenset({"instance", "cloud"})
_REQUIRED_PERMISSION_CAPABILITY = "instance.permissions.read"
_PRINCIPAL_KINDS = frozenset({"email", "email_domain", "organization_group"})
_ACCESS_ROLES = frozenset({"viewer", "editor", "member"})
_PROJECT_ACCESS_ROLES = frozenset({"viewer", "editor"})
_ORGANIZATION_ROLES = frozenset({"owner", "admin", "member"})
_PROJECT_ACCESS_MODES = frozenset({"inherit", "restricted"})
_PROJECT_SYNC_STATUSES = frozenset({"in_sync", "pending", "offline", "error", "deleted"})
_RESOURCE_KINDS = frozenset({"agent", "vault_secret", "skill"})
_RESOURCE_ACCESS_LEVELS = frozenset({"private", "public", "scope"})
_RESOURCE_SYNC_STATUSES = frozenset({"in_sync", "pending", "offline", "error"})
_POLICY_SYNC_STATUSES = frozenset({"none", "in_sync", "applying", "offline", "error"})
_SYNC_COUNT_KEYS = ("active", "error", "offline", "applying", "in_sync")
_PROJECT_ID_PATH_SEPARATORS = frozenset({"/", "\\"})
_PROJECT_ID_DOT_SEGMENTS = frozenset({".", ".."})
logger = logging.getLogger(__name__)
_CACHE_LOCK = threading.RLock()

# Show Page instance-ownership fence constants. These are pairing metadata, not
# Resource ACL: they resolve whether the paired instance is personal or bound to
# an organization so the `/p` sharing axis can stamp group/organization entries.
SHOW_PAGE_INSTANCE_OWNERSHIP_META_KEY = "show_page_instance_ownership"
SHOW_PAGE_OWNERSHIP_CONFIGURATION_UNAVAILABLE = "configuration_unavailable"
_CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE = object()


def _utc_now_iso() -> str:
    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")


class PermissionsError(RuntimeError):
    """Base error for the local Permissions boundary."""


class PermissionsNotPairedError(PermissionsError):
    pass


class PermissionsPairingChangedError(PermissionsError):
    pass


class PermissionsUnavailableError(PermissionsError):
    pass


class PermissionsInvalidResponseError(PermissionsError):
    pass


class PermissionsInvalidRequestError(PermissionsError):
    """The caller asked for something the current-instance API does not serve."""


class PermissionsBackendError(PermissionsError):
    def __init__(self, status: int, payload: Mapping[str, Any] | None = None):
        self.status = status
        self.payload = _error_payload(payload)
        super().__init__(str(self.payload["error"]))


@dataclass(frozen=True)
class PermissionsProjectionResult:
    projection: dict[str, Any]
    source: str
    cached_at: int | None = None
    cache_order: int = 0
    mutation_orders: dict[str, Any] | None = None

    @property
    def offline(self) -> bool:
        return self.source == "cache"


def _error_payload(payload: Mapping[str, Any] | None) -> dict[str, Any]:
    code = payload.get("error") if isinstance(payload, Mapping) else None
    result: dict[str, Any] = {
        "error": code if isinstance(code, str) and code else "permissions_backend_rejected"
    }
    revision = payload.get("current_revision") if isinstance(payload, Mapping) else None
    if isinstance(revision, int) and not isinstance(revision, bool) and revision >= 0:
        result["current_revision"] = revision
    return result


def _strip_sensitive(value: Any) -> Any:
    if isinstance(value, Mapping):
        return {
            str(key): _strip_sensitive(item)
            for key, item in value.items()
            if not any(part in str(key).lower() for part in _SENSITIVE_KEY_PARTS)
        }
    if isinstance(value, list):
        return [_strip_sensitive(item) for item in value]
    if value is None or isinstance(value, (str, int, float, bool)):
        return value
    raise PermissionsInvalidResponseError("permissions_backend_invalid_response")


def _invalid_response() -> NoReturn:
    raise PermissionsInvalidResponseError("permissions_backend_invalid_response")


def _require_mapping(value: Any) -> dict[str, Any]:
    if not isinstance(value, dict):
        _invalid_response()
    return value


def _require_list(value: Any) -> list[Any]:
    if not isinstance(value, list):
        _invalid_response()
    return value


def _require_keys(value: Mapping[str, Any], *keys: str) -> None:
    if any(key not in value for key in keys):
        _invalid_response()


def _require_string(value: Any, *, nullable: bool = False) -> None:
    if value is None and nullable:
        return
    if not isinstance(value, str):
        _invalid_response()


def _require_nonempty_string(value: Any, *, nullable: bool = False) -> None:
    if value is None and nullable:
        return
    if not isinstance(value, str) or not value.strip():
        _invalid_response()


def _require_https_public_url(value: Any) -> None:
    _require_nonempty_string(value)
    if value != value.strip():
        _invalid_response()
    try:
        parsed = urlsplit(value)
        hostname = parsed.hostname
        parsed.port
    except ValueError:
        _invalid_response()
    if (
        parsed.scheme != "https"
        or not parsed.netloc
        or not hostname
        or parsed.username
        or parsed.password
        or parsed.path not in ("", "/")
        or parsed.query
        or parsed.fragment
    ):
        _invalid_response()


def _is_valid_project_id(value: Any) -> bool:
    return (
        isinstance(value, str)
        and bool(value.strip())
        and value not in _PROJECT_ID_DOT_SEGMENTS
        and not any(separator in value for separator in _PROJECT_ID_PATH_SEPARATORS)
    )


def _require_project_id(value: Any) -> None:
    if not _is_valid_project_id(value):
        _invalid_response()


def _require_resource_identity(resource_kind: Any, resource_id: Any) -> tuple[str, str]:
    if not isinstance(resource_kind, str) or resource_kind not in _RESOURCE_KINDS:
        raise PermissionsInvalidRequestError("invalid_resource_kind")
    if (
        not isinstance(resource_id, str)
        or resource_id != resource_id.strip()
        or not resource_id
        or len(resource_id) > 200
        or any(ord(char) < 32 or ord(char) == 127 for char in resource_id)
    ):
        raise PermissionsInvalidRequestError("invalid_resource_id")
    return resource_kind, resource_id


def _require_enum(value: Any, allowed: frozenset[str]) -> None:
    if not isinstance(value, str) or value not in allowed:
        _invalid_response()


def _principal_identity(kind: str, value: str) -> tuple[str, str]:
    normalized = value.strip()
    if kind == "email_domain":
        normalized = normalized.removeprefix("@")
    if kind != "organization_group":
        normalized = normalized.lower()
    return kind, normalized


def _require_unique_identities(identities: list[object]) -> None:
    if len(identities) != len(set(identities)):
        _invalid_response()


def _require_nonnegative_integer(value: Any) -> None:
    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
        _invalid_response()


def _is_backend_unavailable_status(status: int) -> bool:
    return status >= 500 or status in _CACHE_FALLBACK_HTTP_STATUSES


def _validate_access_entries(value: Any) -> list[Any]:
    entries = _require_list(value)
    identities: list[object] = []
    for item in entries:
        entry = _require_mapping(item)
        _require_keys(entry, "kind", "value", "role")
        _require_enum(entry["kind"], _PRINCIPAL_KINDS)
        _require_nonempty_string(entry["value"])
        _require_enum(entry["role"], _ACCESS_ROLES)
        identities.append(_principal_identity(entry["kind"], entry["value"]))
    _require_unique_identities(identities)
    return entries


def _validate_project(value: Any) -> dict[str, Any]:
    project = _require_mapping(value)
    _require_keys(project, "project_id", "organization_id", "display_name", "access", "sync")
    _require_project_id(project["project_id"])
    _require_nonempty_string(project["organization_id"], nullable=True)
    _require_string(project["display_name"])

    access = _require_mapping(project["access"])
    _require_keys(access, "mode", "revision", "bindings")
    _require_enum(access["mode"], _PROJECT_ACCESS_MODES)
    _require_nonnegative_integer(access["revision"])
    binding_identities: list[object] = []
    for item in _require_list(access["bindings"]):
        binding = _require_mapping(item)
        _require_keys(binding, "principal_kind", "principal_value", "access_role")
        _require_enum(binding["principal_kind"], _PRINCIPAL_KINDS)
        _require_nonempty_string(binding["principal_value"])
        _require_enum(binding["access_role"], _PROJECT_ACCESS_ROLES)
        binding_identities.append(
            _principal_identity(binding["principal_kind"], binding["principal_value"])
        )
    _require_unique_identities(binding_identities)

    sync = _require_mapping(project["sync"])
    _require_keys(
        sync,
        "status",
        "desired_access_revision",
        "applied_access_revision",
        "last_synced_at",
    )
    _require_enum(sync["status"], _PROJECT_SYNC_STATUSES)
    _require_nonnegative_integer(sync["desired_access_revision"])
    _require_nonnegative_integer(sync["applied_access_revision"])
    _require_string(sync["last_synced_at"], nullable=True)
    if "last_sync_error" in sync:
        _require_string(sync["last_sync_error"])
    return project


def _validate_sync_counts(value: Any) -> None:
    counts = _require_mapping(value)
    _require_keys(counts, *_SYNC_COUNT_KEYS)
    for key in _SYNC_COUNT_KEYS:
        _require_nonnegative_integer(counts[key])


def _validated_projection(payload: Any, instance_id: str) -> dict[str, Any]:
    if not isinstance(payload, Mapping):
        _invalid_response()
    sanitized = _strip_sensitive(payload)
    projection = _require_mapping(sanitized)
    _require_keys(
        projection,
        "schema_version",
        "instance",
        "capabilities",
        "access",
        "directory",
        "projects",
        "policy_sync",
    )
    if (
        not isinstance(projection["schema_version"], int)
        or isinstance(projection["schema_version"], bool)
        or projection["schema_version"] != 1
    ):
        _invalid_response()

    instance = _require_mapping(projection["instance"])
    _require_keys(
        instance,
        "id",
        "access_mode",
        "permission_authority",
        "local_mutation_allowed",
        "authorization_revision",
    )
    _require_nonempty_string(instance["id"])
    if instance["id"] != instance_id:
        raise PermissionsInvalidResponseError("permissions_instance_mismatch")
    _require_enum(instance["access_mode"], _ACCESS_MODES)
    _require_enum(instance["permission_authority"], _PERMISSION_AUTHORITIES)
    if not isinstance(instance["local_mutation_allowed"], bool):
        _invalid_response()
    _require_nonnegative_integer(instance["authorization_revision"])
    if "name" in instance:
        _require_nonempty_string(instance["name"])
    if "public_url" in instance:
        _require_https_public_url(instance["public_url"])
    if "organization" in instance and instance["organization"] is not None:
        organization = _require_mapping(instance["organization"])
        _require_keys(organization, "id", "name")
        _require_nonempty_string(organization["id"])
        _require_nonempty_string(organization["name"])

    capabilities = _require_list(projection["capabilities"])
    for capability in capabilities:
        if not isinstance(capability, str) or not capability:
            _invalid_response()
    if (
        _REQUIRED_PERMISSION_CAPABILITY not in capabilities
        or len(capabilities) != len(set(capabilities))
    ):
        _invalid_response()

    access = _require_mapping(projection["access"])
    _require_keys(access, "owner", "entries")
    owner = _require_mapping(access["owner"])
    _require_keys(owner, "email", "role")
    _require_nonempty_string(owner["email"], nullable=True)
    if owner["role"] != "owner":
        _invalid_response()
    _validate_access_entries(access["entries"])

    directory = _require_mapping(projection["directory"])
    _require_keys(directory, "members", "groups")
    member_ids: list[object] = []
    for item in _require_list(directory["members"]):
        member = _require_mapping(item)
        _require_keys(member, "id", "email", "organization_role", "group_ids")
        _require_nonempty_string(member["id"])
        _require_nonempty_string(member["email"])
        _require_enum(member["organization_role"], _ORGANIZATION_ROLES)
        member_group_ids = _require_list(member["group_ids"])
        for group_id in member_group_ids:
            _require_nonempty_string(group_id)
        member_ids.append(member["id"])
        _require_unique_identities(member_group_ids)
    _require_unique_identities(member_ids)

    directory_group_ids: list[object] = []
    for item in _require_list(directory["groups"]):
        group = _require_mapping(item)
        _require_keys(group, "id", "name", "archived_at")
        _require_nonempty_string(group["id"])
        _require_string(group["name"])
        _require_string(group["archived_at"], nullable=True)
        directory_group_ids.append(group["id"])
    _require_unique_identities(directory_group_ids)

    project_ids: list[object] = []
    for project_value in _require_list(projection["projects"]):
        project = _validate_project(project_value)
        project_ids.append(project["project_id"])
    _require_unique_identities(project_ids)

    policy_sync = _require_mapping(projection["policy_sync"])
    _require_keys(policy_sync, "status", "projects", "resources")
    _require_enum(policy_sync["status"], _POLICY_SYNC_STATUSES)
    _validate_sync_counts(policy_sync["projects"])
    _validate_sync_counts(policy_sync["resources"])
    return projection


def _validated_authorized_users_result(payload: Any) -> dict[str, Any]:
    result = _require_mapping(_strip_sensitive(payload))
    _require_keys(result, "ok", "entries", "authorization_revision")
    if result["ok"] is not True:
        _invalid_response()
    _validate_access_entries(result["entries"])
    _require_nonnegative_integer(result["authorization_revision"])
    return result


def _validated_project_result(payload: Any, project_id: str) -> dict[str, Any]:
    result = _require_mapping(_strip_sensitive(payload))
    _require_keys(result, "ok", "project", "authorization_revision")
    if result["ok"] is not True:
        _invalid_response()
    project = _validate_project(result["project"])
    if project["project_id"] != project_id:
        _invalid_response()
    _require_nonnegative_integer(result["authorization_revision"])
    return result


def _validate_resource(
    value: Any,
    *,
    instance_id: str,
    resource_kind: str,
    resource_id: str,
) -> dict[str, Any]:
    resource = _require_mapping(value)
    _require_keys(
        resource,
        "instance_id",
        "resource_kind",
        "resource_id",
        "display_name",
        "owner_user_id",
        "access",
        "sync",
    )
    if (
        resource["instance_id"] != instance_id
        or resource["resource_kind"] != resource_kind
        or resource["resource_id"] != resource_id
    ):
        raise PermissionsInvalidResponseError("permissions_resource_mismatch")
    _require_string(resource["display_name"])
    _require_nonempty_string(resource["owner_user_id"], nullable=True)

    access = _require_mapping(resource["access"])
    _require_keys(access, "access_level", "group_ids", "revision")
    _require_enum(access["access_level"], _RESOURCE_ACCESS_LEVELS)
    group_ids = _require_list(access["group_ids"])
    for group_id in group_ids:
        _require_nonempty_string(group_id)
    if len(group_ids) != len(set(group_ids)):
        _invalid_response()
    if access["access_level"] == "scope":
        if not group_ids:
            _invalid_response()
    elif group_ids:
        _invalid_response()
    _require_nonnegative_integer(access["revision"])

    sync = _require_mapping(resource["sync"])
    _require_keys(
        sync,
        "status",
        "desired_acl_revision",
        "applied_acl_revision",
        "last_synced_at",
    )
    _require_enum(sync["status"], _RESOURCE_SYNC_STATUSES)
    _require_nonnegative_integer(sync["desired_acl_revision"])
    _require_nonnegative_integer(sync["applied_acl_revision"])
    _require_string(sync["last_synced_at"], nullable=True)
    if "last_sync_error" in sync:
        _require_string(sync["last_sync_error"])
    return resource


def _validated_resource_result(
    payload: Any,
    *,
    instance_id: str,
    resource_kind: str,
    resource_id: str,
    mutation: bool,
    pairing_guard: Callable[[], None] | None = None,
) -> dict[str, Any]:
    result = _require_mapping(_strip_sensitive(payload))
    _require_keys(result, "resource")
    if mutation:
        _require_keys(result, "ok")
        if result["ok"] is not True:
            _invalid_response()
    result["resource"] = _validate_resource(
        result["resource"],
        instance_id=instance_id,
        resource_kind=resource_kind,
        resource_id=resource_id,
    )
    if pairing_guard is not None:
        pairing_guard()
    return result


def _runtime_credentials(config: V2Config) -> tuple[str, str, str]:
    credentials = config.remote_access.vibe_cloud.runtime_credentials()
    if credentials is None:
        raise PermissionsNotPairedError("permissions_not_paired")
    return credentials


def _request_config(
    config: V2Config | None,
) -> tuple[V2Config, Callable[[], V2Config]]:
    return (config if config is not None else V2Config.load()), V2Config.load


def _guard_current_pairing(
    credentials: tuple[str, str, str],
    load_current_config: Callable[[], V2Config],
) -> None:
    try:
        current_credentials = _runtime_credentials(load_current_config())
    except (OSError, TypeError, ValueError, PermissionsNotPairedError) as exc:
        raise PermissionsPairingChangedError("permissions_pairing_changed") from exc
    if current_credentials != credentials:
        raise PermissionsPairingChangedError("permissions_pairing_changed")


def _mutation_payload(payload: Mapping[str, Any]) -> tuple[str, dict[str, Any]]:
    expected_instance_id = payload.get("if_match_instance_id")
    if not isinstance(expected_instance_id, str) or not expected_instance_id:
        raise PermissionsInvalidResponseError("invalid_request")
    backend_payload = dict(payload)
    del backend_payload["if_match_instance_id"]
    return expected_instance_id, backend_payload


def _cache_path() -> Path:
    return paths.get_state_dir() / CACHE_FILENAME


def _cache_order_path() -> Path:
    return paths.get_state_dir() / CACHE_ORDER_FILENAME


def _cache_file_lock(path: Path):
    """Return the cross-process lock for projection read-compare-write updates."""

    # Import lazily because storage's package initializer imports V2Config.
    from storage.lock import MigrationFileLock

    return MigrationFileLock(path.with_name(f".{path.stem}.lock"))


def _atomic_write_json(path: Path, value: Any) -> None:
    # Compact and ASCII-only: nothing reads these projections by eye, and the
    # cache is re-read on every permission check, so bytes matter more than
    # legibility. The swap itself belongs to ``write_atomic``.
    write_atomic(path, json.dumps(value, ensure_ascii=True, separators=(",", ":")))


def _write_cache(
    instance_id: str,
    projection: dict[str, Any],
    *,
    cache_order: int = 0,
    mutation_orders: Mapping[str, Any] | None = None,
) -> None:
    envelope = {
        "cache_schema_version": CACHE_SCHEMA_VERSION,
        "instance_id": instance_id,
        "cached_at": int(time.time()),
        "cache_order": cache_order,
        "projection": projection,
    }
    normalized_orders = _normalize_mutation_orders(mutation_orders, projection)
    if normalized_orders:
        envelope["mutation_orders"] = normalized_orders
    _atomic_write_json(_cache_path(), envelope)


def _valid_cache_order(value: Any) -> bool:
    return isinstance(value, int) and not isinstance(value, bool) and value >= 0


def _normalize_mutation_orders(
    value: Any,
    projection: Mapping[str, Any],
) -> dict[str, Any]:
    """Keep optional per-entity mutation freshness metadata well-shaped."""

    if not isinstance(value, Mapping):
        return {}
    normalized: dict[str, Any] = {}
    access_order = value.get("access")
    if _valid_cache_order(access_order):
        normalized["access"] = access_order
    project_orders = value.get("projects")
    if isinstance(project_orders, Mapping):
        project_ids = {
            project.get("project_id")
            for project in projection.get("projects", [])
            if isinstance(project, Mapping)
        }
        normalized_projects = {
            str(project_id): order
            for project_id, order in project_orders.items()
            if project_id in project_ids and _valid_cache_order(order)
        }
        if normalized_projects:
            normalized["projects"] = normalized_projects
    return normalized


def _read_cache(instance_id: str) -> PermissionsProjectionResult | None:
    try:
        envelope = json.loads(_cache_path().read_text(encoding="utf-8"))
    except (FileNotFoundError, OSError, UnicodeDecodeError, json.JSONDecodeError):
        return None
    if not isinstance(envelope, dict):
        return None
    if envelope.get("cache_schema_version") != CACHE_SCHEMA_VERSION:
        return None
    if envelope.get("instance_id") != instance_id:
        return None
    cached_at = envelope.get("cached_at")
    if not isinstance(cached_at, int) or isinstance(cached_at, bool) or cached_at < 0:
        return None
    cache_order = envelope.get("cache_order", 0)
    if not isinstance(cache_order, int) or isinstance(cache_order, bool) or cache_order < 0:
        return None
    try:
        projection = _validated_projection(envelope.get("projection"), instance_id)
    except PermissionsInvalidResponseError:
        return None
    mutation_orders = _normalize_mutation_orders(
        envelope.get("mutation_orders"),
        projection,
    )
    return PermissionsProjectionResult(
        projection=projection,
        source="cache",
        cached_at=cached_at,
        cache_order=cache_order,
        mutation_orders=mutation_orders,
    )


def _read_pairing_bound_cache(
    instance_id: str,
    pairing_guard: Callable[[], None],
) -> PermissionsProjectionResult | None:
    """Read a fallback projection only while the captured pairing remains current."""

    pairing_guard()
    cached = _read_cache(instance_id)
    pairing_guard()
    return cached


def _read_cache_order() -> int:
    try:
        value = json.loads(_cache_order_path().read_text(encoding="utf-8"))
    except (FileNotFoundError, OSError, UnicodeDecodeError, json.JSONDecodeError):
        return 0
    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
        return 0
    return value


def _cache_allocate_order(instance_id: str) -> int:
    """Reserve a request-start order shared by controller and UI processes."""

    with _CACHE_LOCK:
        try:
            cache_path = _cache_path()
            cache_path.parent.mkdir(parents=True, exist_ok=True)
            with _cache_file_lock(cache_path):
                cached = _read_cache(instance_id)
                current = max(
                    _read_cache_order(),
                    cached.cache_order if cached is not None else 0,
                )
                reserved = current + 1
                _atomic_write_json(_cache_order_path(), reserved)
                return reserved
        except (OSError, TimeoutError):
            logger.warning(
                "Unable to reserve the Permissions cache request order",
                exc_info=True,
            )
    # The written cache envelope will make this fallback visible to later writers.
    return max(time.time_ns(), 1)


def _prefer_mapping(
    preferred: Mapping[str, Any],
    fallback: Mapping[str, Any],
) -> dict[str, Any]:
    """Prefer one mapping while retaining additive fields from the other."""

    merged = dict(fallback)
    for key, value in preferred.items():
        previous = merged.get(key)
        if isinstance(value, Mapping) and isinstance(previous, Mapping):
            merged[key] = _prefer_mapping(value, previous)
        else:
            merged[key] = value
    return merged


def _merge_project_projection(
    preferred: Mapping[str, Any],
    fallback: Mapping[str, Any],
) -> dict[str, Any]:
    """Merge one Project while preserving the caller-selected snapshot winner.

    Equal-revision snapshots are ordered by their request-start epoch at the
    outer projection boundary. A status ranking here would let an older
    ``applying``/``pending`` response overwrite a newer terminal failure.
    Mutation acknowledgements also use this helper so their authoritative
    Project fields are retained while additive unknown fields survive.
    """

    return _prefer_mapping(preferred, fallback)


def _merge_project_mutation_acknowledgement(
    acknowledged: Mapping[str, Any],
    cached: Mapping[str, Any],
) -> dict[str, Any]:
    """Merge one Project mutation without regressing its policy revision."""

    if cached["access"]["revision"] > acknowledged["access"]["revision"]:
        return _merge_project_projection(cached, acknowledged)
    return _merge_project_projection(acknowledged, cached)


def _merge_projects(
    preferred: list[Any],
    fallback: list[Any],
) -> list[dict[str, Any]]:
    fallback_by_id = {project["project_id"]: project for project in fallback}
    return [
        _merge_project_projection(project, fallback_by_id[project["project_id"]])
        if project["project_id"] in fallback_by_id
        else dict(project)
        for project in preferred
    ]


def _merge_policy_sync(
    preferred: Mapping[str, Any],
    fallback: Mapping[str, Any],
) -> dict[str, Any]:
    """Preserve the request-order winner for aggregate sync state."""

    return _prefer_mapping(preferred, fallback)


def _merge_equal_revision_projection(
    cached: dict[str, Any],
    candidate: dict[str, Any],
    *,
    prefer_candidate: bool,
) -> dict[str, Any]:
    preferred, fallback = (
        (candidate, cached) if prefer_candidate else (cached, candidate)
    )
    merged = _prefer_mapping(preferred, fallback)
    merged["projects"] = _merge_projects(
        preferred["projects"],
        fallback["projects"],
    )
    merged["policy_sync"] = _merge_policy_sync(
        preferred["policy_sync"],
        fallback["policy_sync"],
    )
    return merged


def _merge_mutation_rebase_projection(
    cached: dict[str, Any],
    candidate: dict[str, Any],
    *,
    mutation_target: tuple[str, str | None] | None,
    cached_mutation_orders: Mapping[str, Any],
    request_order: int,
) -> dict[str, Any]:
    """Apply a delayed mutation without regressing newer entity state."""

    merged = _prefer_mapping(candidate, cached)
    if mutation_target is not None and mutation_target[0] == "access":
        cached_access_order = cached_mutation_orders.get("access")
        if _valid_cache_order(cached_access_order) and cached_access_order > request_order:
            # Access entries have no backend entity revision. Their mutation
            # order is the only durable ordering signal across processes.
            merged["access"] = _prefer_mapping(
                cached["access"],
                candidate["access"],
            )
    cached_projects = {
        project["project_id"]: project for project in cached["projects"]
    }
    projects: list[dict[str, Any]] = []
    for project in candidate["projects"]:
        cached_project = cached_projects.get(project["project_id"])
        if cached_project is None:
            projects.append(dict(project))
            continue
        merged_project = _merge_project_mutation_acknowledgement(
            project,
            cached_project,
        )
        merged_project["sync"] = _prefer_mapping(
            cached_project["sync"],
            project["sync"],
        )
        projects.append(merged_project)
    merged["projects"] = projects
    return merged


def _cache_read_merge_write(
    instance_id: str,
    merge: Callable[[dict[str, Any] | None], Any],
    *,
    request_order: int,
    mutation_rebase: bool = False,
    mutation_target: tuple[str, str | None] | None = None,
    complete_projection: bool = False,
    pairing_guard: Callable[[], None] | None = None,
) -> None:
    """Read, merge, and atomically replace one instance cache under one lock."""

    with _CACHE_LOCK:
        try:
            cache_path = _cache_path()
            cache_path.parent.mkdir(parents=True, exist_ok=True)
            with _cache_file_lock(cache_path):
                if pairing_guard is not None:
                    pairing_guard()
                cached = _read_cache(instance_id)
                candidate = merge(cached.projection if cached is not None else None)
                if candidate is None:
                    return
                validated = _validated_projection(candidate, instance_id)
                cache_order = request_order
                cached_mutation_orders = (
                    cached.mutation_orders if cached is not None else {}
                ) or {}
                candidate_wins_complete_projection = cached is None
                if cached is not None:
                    cached_revision = cached.projection["instance"][
                        "authorization_revision"
                    ]
                    candidate_revision = validated["instance"][
                        "authorization_revision"
                    ]
                    if cached_revision > candidate_revision:
                        return
                    cache_order = max(cached.cache_order, request_order)
                    candidate_wins_complete_projection = (
                        candidate_revision > cached_revision
                        or (
                            candidate_revision == cached_revision
                            and request_order >= cached.cache_order
                        )
                    )
                    if cached_revision == candidate_revision and not mutation_rebase:
                        validated = _merge_equal_revision_projection(
                            cached.projection,
                            validated,
                            prefer_candidate=(
                                request_order >= cached.cache_order
                                if request_order and cached.cache_order
                                else request_order > 0
                            ),
                        )
                        validated = _validated_projection(validated, instance_id)
                    elif (
                        cached_revision == candidate_revision
                        and mutation_rebase
                        and cached.cache_order > request_order
                    ):
                        validated = _merge_mutation_rebase_projection(
                            cached.projection,
                            validated,
                            mutation_target=mutation_target,
                            cached_mutation_orders=cached_mutation_orders,
                            request_order=request_order,
                        )
                        validated = _validated_projection(validated, instance_id)
                mutation_orders = dict(cached_mutation_orders)
                if complete_projection and candidate_wins_complete_projection:
                    # A newer complete read is authoritative for every entity;
                    # older mutation markers must not affect later rebases.
                    mutation_orders = {}
                elif mutation_target is not None:
                    target_kind, target_id = mutation_target
                    if target_kind == "access":
                        current_order = mutation_orders.get("access")
                        if not _valid_cache_order(current_order) or request_order > current_order:
                            mutation_orders["access"] = request_order
                    elif target_kind == "project" and target_id is not None:
                        project_orders = dict(mutation_orders.get("projects") or {})
                        current_order = project_orders.get(target_id)
                        if not _valid_cache_order(current_order) or request_order > current_order:
                            project_orders[target_id] = request_order
                        mutation_orders["projects"] = project_orders
                if pairing_guard is not None:
                    pairing_guard()
                _write_cache(
                    instance_id,
                    validated,
                    cache_order=cache_order,
                    mutation_orders=mutation_orders,
                )
        except (OSError, TimeoutError):
            logger.warning("Unable to cache the current Permissions projection", exc_info=True)


def _cache_projection(
    instance_id: str,
    projection: Any,
    *,
    request_order: int | None = None,
    pairing_guard: Callable[[], None] | None = None,
) -> None:
    order = _cache_allocate_order(instance_id) if request_order is None else request_order
    _cache_read_merge_write(
        instance_id,
        lambda _cached: projection,
        request_order=order,
        complete_projection=True,
        pairing_guard=pairing_guard,
    )


def _cache_mutation_result(
    instance_id: str,
    authorization_revision: int,
    *,
    access_entries: list[Any] | None = None,
    project: Mapping[str, Any] | None = None,
    request_order: int | None = None,
    pairing_guard: Callable[[], None] | None = None,
) -> None:
    def merge(cached: dict[str, Any] | None) -> dict[str, Any] | None:
        if cached is None:
            return None
        current_revision = cached["instance"]["authorization_revision"]
        # A mutation acknowledgement can arrive after a newer global revision
        # was cached by another mutation. Keep that newer fence while replaying
        # the entity that this acknowledgement actually committed.
        effective_revision = max(current_revision, authorization_revision)
        projection = {
            **cached,
            "instance": {
                **cached["instance"],
                "authorization_revision": effective_revision,
            },
        }
        if access_entries is not None:
            projection["access"] = {
                **cached["access"],
                "entries": access_entries,
            }
        if project is not None:
            project_id = project.get("project_id")
            cached_project = next(
                (
                    current
                    for current in cached["projects"]
                    if current.get("project_id") == project_id
                ),
                None,
            )
            merged_project = (
                _merge_project_mutation_acknowledgement(project, cached_project)
                if cached_project is not None
                else project
            )
            projects = [
                merged_project if current.get("project_id") == project_id else current
                for current in cached["projects"]
            ]
            if not any(current.get("project_id") == project_id for current in projects):
                projects.append(merged_project)
            projection["projects"] = projects
        return projection

    order = _cache_allocate_order(instance_id) if request_order is None else request_order
    _cache_read_merge_write(
        instance_id,
        merge,
        request_order=order,
        mutation_rebase=True,
        mutation_target=(
            ("access", None)
            if access_entries is not None
            else ("project", str(project.get("project_id")))
            if project is not None
            else None
        ),
        pairing_guard=pairing_guard,
    )


def _acknowledge_authorization_revision(
    config: V2Config,
    revision: int,
    pairing_guard: Callable[[], None] | None = None,
) -> None:
    from vibe import remote_access

    try:
        remote_access.acknowledge_authorization_revision(
            config,
            revision,
            pairing_guard=pairing_guard,
        )
    except remote_access.AuthorizationRevisionPairingChangedError as exc:
        raise PermissionsPairingChangedError("permissions_pairing_changed") from exc


def _backend_request(
    config: V2Config,
    load_current_config: Callable[[], V2Config],
    method: str,
    suffix: str,
    payload: Mapping[str, Any] | None = None,
    *,
    expected_instance_id: str | None = None,
    timeout: float = DEFAULT_TIMEOUT_SECONDS,
    credentials: tuple[str, str, str] | None = None,
) -> tuple[dict[str, Any], str]:
    credentials = credentials or _runtime_credentials(config)
    backend_url, instance_id, instance_secret = credentials
    if expected_instance_id is not None and expected_instance_id != instance_id:
        raise PermissionsPairingChangedError("permissions_pairing_changed")
    endpoint = (
        f"{backend_url}/api/v1/instances/{quote(instance_id, safe='')}/permissions"
        f"/{suffix.lstrip('/')}"
        if suffix
        else f"{backend_url}/api/v1/instances/{quote(instance_id, safe='')}/permissions"
    )
    try:
        response = requests.request(
            method,
            endpoint,
            json=dict(payload) if payload is not None else None,
            headers={
                "Accept": "application/json",
                "Content-Type": "application/json",
                "User-Agent": "avibe/dev",
                "X-Vibe-Device-Secret": instance_secret,
            },
            timeout=timeout,
            allow_redirects=False,
        )
    except requests.RequestException as exc:
        _guard_current_pairing(credentials, load_current_config)
        raise PermissionsUnavailableError("permissions_backend_unavailable") from exc
    _guard_current_pairing(credentials, load_current_config)
    if 300 <= response.status_code < 400:
        raise PermissionsInvalidResponseError("permissions_backend_redirect_blocked")
    try:
        parsed = response.json()
    except ValueError as exc:
        if _is_backend_unavailable_status(response.status_code):
            raise PermissionsUnavailableError("permissions_backend_unavailable") from exc
        raise PermissionsInvalidResponseError("permissions_backend_invalid_response") from exc
    if not isinstance(parsed, dict):
        if _is_backend_unavailable_status(response.status_code):
            raise PermissionsUnavailableError("permissions_backend_unavailable")
        raise PermissionsInvalidResponseError("permissions_backend_invalid_response")
    if not response.ok:
        raise PermissionsBackendError(response.status_code, parsed)
    return parsed, instance_id


def get_current_permissions(config: V2Config | None = None) -> PermissionsProjectionResult:
    config, load_current_config = _request_config(config)
    credentials = _runtime_credentials(config)
    _, instance_id, _ = credentials
    request_order = _cache_allocate_order(instance_id)
    pairing_guard = lambda: _guard_current_pairing(credentials, load_current_config)
    try:
        payload, _ = _backend_request(config, load_current_config, "GET", "")
        projection = _validated_projection(payload, instance_id)
        _cache_projection(
            instance_id,
            projection,
            request_order=request_order,
            pairing_guard=pairing_guard,
        )
        # Cache persistence is best effort; it may fail before its locked
        # boundary guard runs. Recheck before publishing the live projection.
        pairing_guard()
        return PermissionsProjectionResult(
            projection=projection,
            source="live",
            cache_order=request_order,
        )
    except PermissionsUnavailableError:
        cached = _read_pairing_bound_cache(instance_id, pairing_guard)
        if cached is not None:
            return cached
        raise
    except PermissionsBackendError as exc:
        if _is_backend_unavailable_status(exc.status):
            cached = _read_pairing_bound_cache(instance_id, pairing_guard)
            if cached is not None:
                return cached
        raise


def replace_authorized_users(
    payload: Mapping[str, Any],
    config: V2Config | None = None,
) -> dict[str, Any]:
    config, load_current_config = _request_config(config)
    expected_instance_id, backend_payload = _mutation_payload(payload)
    credentials = _runtime_credentials(config)
    _, request_instance_id, _ = credentials
    request_order = _cache_allocate_order(request_instance_id)
    pairing_guard = lambda: _guard_current_pairing(credentials, load_current_config)
    payload_result, instance_id = _backend_request(
        config,
        load_current_config,
        "PUT",
        "authorized-users",
        backend_payload,
        expected_instance_id=expected_instance_id,
    )
    result = _validated_authorized_users_result(payload_result)
    pairing_guard()
    _acknowledge_authorization_revision(
        config,
        result["authorization_revision"],
        pairing_guard,
    )
    _cache_mutation_result(
        instance_id,
        result["authorization_revision"],
        access_entries=result["entries"],
        request_order=request_order,
        pairing_guard=pairing_guard,
    )
    pairing_guard()
    return {**result, "instance_id": instance_id}


def update_project_access(
    project_id: str,
    payload: Mapping[str, Any],
    config: V2Config | None = None,
) -> dict[str, Any]:
    if not _is_valid_project_id(project_id):
        raise PermissionsInvalidResponseError("invalid_project_id")
    config, load_current_config = _request_config(config)
    expected_instance_id, backend_payload = _mutation_payload(payload)
    credentials = _runtime_credentials(config)
    _, request_instance_id, _ = credentials
    request_order = _cache_allocate_order(request_instance_id)
    pairing_guard = lambda: _guard_current_pairing(credentials, load_current_config)
    payload_result, instance_id = _backend_request(
        config,
        load_current_config,
        "PUT",
        f"projects/{quote(project_id, safe='')}/access",
        backend_payload,
        expected_instance_id=expected_instance_id,
    )
    result = _validated_project_result(payload_result, project_id)
    pairing_guard()
    _acknowledge_authorization_revision(
        config,
        result["authorization_revision"],
        pairing_guard,
    )
    _cache_mutation_result(
        instance_id,
        result["authorization_revision"],
        project=result["project"],
        request_order=request_order,
        pairing_guard=pairing_guard,
    )
    pairing_guard()
    return {**result, "instance_id": instance_id}


def get_resource_access(
    resource_kind: str,
    resource_id: str,
    config: V2Config | None = None,
) -> dict[str, Any]:
    resource_kind, resource_id = _require_resource_identity(resource_kind, resource_id)
    config, load_current_config = _request_config(config)
    credentials = _runtime_credentials(config)
    pairing_guard = lambda: _guard_current_pairing(credentials, load_current_config)
    payload_result, instance_id = _backend_request(
        config,
        load_current_config,
        "GET",
        f"resources/{quote(resource_kind, safe='')}/{quote(resource_id, safe='')}/access",
        credentials=credentials,
    )
    return _validated_resource_result(
        payload_result,
        instance_id=instance_id,
        resource_kind=resource_kind,
        resource_id=resource_id,
        mutation=False,
        pairing_guard=pairing_guard,
    )


def update_resource_access(
    resource_kind: str,
    resource_id: str,
    payload: Mapping[str, Any],
    config: V2Config | None = None,
) -> dict[str, Any]:
    resource_kind, resource_id = _require_resource_identity(resource_kind, resource_id)
    config, load_current_config = _request_config(config)
    credentials = _runtime_credentials(config)
    pairing_guard = lambda: _guard_current_pairing(credentials, load_current_config)
    expected_instance_id, backend_payload = _mutation_payload(payload)
    payload_result, instance_id = _backend_request(
        config,
        load_current_config,
        "PUT",
        f"resources/{quote(resource_kind, safe='')}/{quote(resource_id, safe='')}/access",
        backend_payload,
        expected_instance_id=expected_instance_id,
        credentials=credentials,
    )
    return _validated_resource_result(
        payload_result,
        instance_id=instance_id,
        resource_kind=resource_kind,
        resource_id=resource_id,
        mutation=True,
        pairing_guard=pairing_guard,
    )


def _clean_show_page_identifier(value: Any, *, limit: int = 200) -> str | None:
    if not isinstance(value, str):
        return None
    cleaned = value.strip()
    if not cleaned or len(cleaned) > limit or any(ord(char) < 32 or ord(char) == 127 for char in cleaned):
        return None
    return cleaned


def _configured_show_page_instance() -> tuple[str, str] | None | object:
    try:
        cloud = V2Config.load().remote_access.vibe_cloud
        credentials = cloud.runtime_credentials()
        if credentials is None:
            return None
        if not isinstance(credentials, (tuple, list)) or len(credentials) != 3:
            return _CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE
        instance_id = _clean_show_page_identifier(credentials[1])
        if instance_id is None or cloud.instance_kind not in {"personal", "organization"}:
            return _CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE
    except (
        AttributeError,
        FileNotFoundError,
        IndexError,
        KeyError,
        OSError,
        TypeError,
        ValueError,
    ):
        return _CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE
    return instance_id, cloud.instance_kind


def _show_page_configuration_unavailable_ownership() -> dict[str, Any]:
    return {
        "mode": SHOW_PAGE_OWNERSHIP_CONFIGURATION_UNAVAILABLE,
        "instance_id": None,
        "organization_id": None,
        "source": "config",
    }


def _stored_show_page_instance_ownership(connection: Connection) -> dict[str, Any] | None:
    raw_value = connection.execute(
        select(state_meta.c.value_json).where(
            state_meta.c.key == SHOW_PAGE_INSTANCE_OWNERSHIP_META_KEY
        )
    ).scalar_one_or_none()
    try:
        payload = json.loads(raw_value) if raw_value else None
    except (TypeError, ValueError):
        return None
    if not isinstance(payload, dict) or payload.get("schema_version") != 1:
        return None
    instance_id = _clean_show_page_identifier(payload.get("instance_id"))
    mode = payload.get("mode")
    organization_id = _clean_show_page_identifier(payload.get("organization_id"))
    if instance_id is None or mode not in {"personal", "organization"}:
        return None
    if mode == "organization" and organization_id is None:
        return None
    if mode == "personal" and organization_id is not None:
        return None
    return {
        "mode": mode,
        "instance_id": instance_id,
        "organization_id": organization_id,
        "source": "stored",
    }


def current_show_page_instance_ownership(
    *,
    connection: Connection | None = None,
) -> dict[str, Any]:
    """Return the persisted ownership fence for the exact current pairing."""

    configured = _configured_show_page_instance()
    if configured is _CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE:
        return _show_page_configuration_unavailable_ownership()
    if configured is None:
        return {
            "mode": "unmanaged",
            "instance_id": None,
            "organization_id": None,
            "source": "config",
        }
    instance_id, instance_kind = configured
    if connection is not None:
        stored = _stored_show_page_instance_ownership(connection)
    else:
        engine = get_cached_sqlite_engine()
        with engine.begin() as conn:
            stored = _stored_show_page_instance_ownership(conn)
    exact_stored = stored if stored and stored["instance_id"] == instance_id else None
    if instance_kind == "personal":
        return {
            "mode": "personal",
            "instance_id": instance_id,
            "organization_id": None,
            "source": "config",
        }
    if instance_kind == "organization":
        if exact_stored and exact_stored["mode"] == "organization":
            return exact_stored
        return {
            "mode": "organization_pending",
            "instance_id": instance_id,
            "organization_id": None,
            "source": "config",
        }
    if exact_stored is not None:
        return exact_stored
    return {
        "mode": "unmanaged",
        "instance_id": instance_id,
        "organization_id": None,
        "source": "config",
    }


def remember_show_page_instance_ownership(
    connection: Connection,
    ownership: Mapping[str, Any],
) -> dict[str, Any]:
    """Persist an authoritative binding only while its exact pairing is current."""

    with config_file_lock():
        return _remember_show_page_instance_ownership_locked(connection, ownership)


def _remember_show_page_instance_ownership_locked(
    connection: Connection,
    ownership: Mapping[str, Any],
) -> dict[str, Any]:
    """Implement ownership persistence while the pairing lock is held."""

    configured = _configured_show_page_instance()
    instance_id = _clean_show_page_identifier(ownership.get("instance_id"))
    mode = ownership.get("mode")
    organization_id = _clean_show_page_identifier(ownership.get("organization_id"))
    if (
        configured is None
        or configured is _CONFIGURED_SHOW_PAGE_INSTANCE_UNAVAILABLE
        or instance_id is None
        or instance_id != configured[0]
        or mode not in {"personal", "organization"}
        or configured[1] != mode
        or (mode == "organization") != bool(organization_id)
    ):
        return current_show_page_instance_ownership(connection=connection)
    payload = {
        "schema_version": 1,
        "instance_id": instance_id,
        "mode": mode,
        "organization_id": organization_id,
    }
    connection.execute(
        state_meta.delete().where(state_meta.c.key == SHOW_PAGE_INSTANCE_OWNERSHIP_META_KEY)
    )
    connection.execute(
        state_meta.insert().values(
            key=SHOW_PAGE_INSTANCE_OWNERSHIP_META_KEY,
            value_json=json.dumps(payload, separators=(",", ":")),
            updated_at=_utc_now_iso(),
        )
    )
    return {**payload, "source": str(ownership.get("source") or "live")}


def resolve_current_instance_ownership(
    config: V2Config | None = None,
) -> dict[str, Any]:
    """Resolve exact-instance ownership without trusting browser claims."""

    try:
        config = config or V2Config.load()
        credentials = config.remote_access.vibe_cloud.runtime_credentials()
    except (
        AttributeError,
        FileNotFoundError,
        IndexError,
        KeyError,
        OSError,
        TypeError,
        ValueError,
    ):
        return {
            "mode": SHOW_PAGE_OWNERSHIP_CONFIGURATION_UNAVAILABLE,
            "instance_id": None,
            "organization_id": None,
            "source": "config",
        }
    if credentials is None:
        return {
            "mode": "unmanaged",
            "instance_id": None,
            "organization_id": None,
            "source": "config",
        }
    if (
        not isinstance(credentials, (tuple, list))
        or len(credentials) != 3
        or not isinstance(credentials[1], str)
        or not credentials[1].strip()
    ):
        return {
            "mode": SHOW_PAGE_OWNERSHIP_CONFIGURATION_UNAVAILABLE,
            "instance_id": None,
            "organization_id": None,
            "source": "config",
        }

    current = current_show_page_instance_ownership()
    if current["mode"] in {
        "personal",
        "organization",
        SHOW_PAGE_OWNERSHIP_CONFIGURATION_UNAVAILABLE,
    }:
        return current
    try:
        result = get_current_permissions(config)
    except (PermissionsError, OSError, TypeError, ValueError):
        return current
    instance = result.projection["instance"]
    organization = instance.get("organization")
    if isinstance(organization, Mapping):
        ownership = {
            "mode": "organization",
            "instance_id": credentials[1],
            "organization_id": organization["id"],
            "source": result.source,
        }
    elif "organization" in instance or config.remote_access.vibe_cloud.instance_kind == "personal":
        ownership = {
            "mode": "personal",
            "instance_id": credentials[1],
            "organization_id": None,
            "source": result.source,
        }
    else:
        return current
    # Persist a definitive binding so a later offline resolution falls back to
    # the exact-instance fence instead of re-querying the Permissions backend.
    engine = get_cached_sqlite_engine()
    with engine.begin() as conn:
        return remember_show_page_instance_ownership(conn, ownership)


def _local_instance_display(
    config: V2Config,
    instance_id: str,
) -> dict[str, str]:
    cloud = config.remote_access.vibe_cloud
    if str(cloud.instance_id or "").strip() != instance_id:
        return {}
    public_url = str(cloud.public_url or "").strip()
    try:
        _require_https_public_url(public_url)
        parsed = urlsplit(public_url)
    except PermissionsInvalidResponseError:
        return {}
    hostname = parsed.hostname or ""
    name = hostname.split(".", 1)[0]
    if name.endswith("-app"):
        name = name[:-4]
    if not name:
        return {}
    return {
        "name": name,
        "public_url": f"https://{parsed.netloc.lower().rstrip('.')}",
    }


def response_payload(
    result: PermissionsProjectionResult,
    config: V2Config | None = None,
) -> dict[str, Any]:
    projection = result.projection
    instance = projection["instance"]
    if "name" not in instance or "public_url" not in instance:
        try:
            local_display = _local_instance_display(config or V2Config.load(), instance["id"])
        except (FileNotFoundError, OSError, TypeError, ValueError):
            local_display = {}
        if local_display:
            instance = {**local_display, **instance}
            projection = {**projection, "instance": instance}
    return {
        "ok": True,
        "source": result.source,
        "offline": result.offline,
        "cached_at": result.cached_at,
        "projection": projection,
    }