"""Idempotency keys for connector execute intents.

Cloud jobs are unique on ``(project_id, idempotency_key)``. A content-hash
default treats every list/read with the same input as the same job forever,
so Refresh returns a stale object list after uploads.
"""

from __future__ import annotations

from uuid import uuid4


def execute_idempotency_key(explicit: str | None) -> str:
    """Use the client key when provided; otherwise mint a new execute intent."""
    key = (explicit or "").strip()
    return key or f"conn_exec_{uuid4().hex}"