"""Canonical identity helpers for durable AwoooP runtime runs.

The durable ``awooop_run_state.run_id`` is the root identity.  Trace and work
item identifiers are derived from it so retries, API readback, channel mirrors,
and downstream receipts cannot silently invent unrelated correlation values.
"""

from __future__ import annotations

import hashlib
import re
import secrets
import time
from dataclasses import dataclass
from uuid import UUID

_PROJECT_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
_TRACEPARENT_RE = re.compile(
    r"^00-(?!0{32})[0-9a-f]{32}-(?!0{16})[0-9a-f]{16}-01$"
)


@dataclass(frozen=True, slots=True)
class RuntimeCorrelation:
    """Public-safe identity shared by every node in one runtime run."""

    run_id: UUID
    trace_id: str
    work_item_id: str

    def public_dict(self) -> dict[str, str]:
        return {
            "run_id": str(self.run_id),
            "trace_id": self.trace_id,
            "work_item_id": self.work_item_id,
        }


def new_uuid7(
    *,
    timestamp_ms: int | None = None,
    entropy: int | None = None,
) -> UUID:
    """Return an RFC 9562 UUIDv7 with the RFC 4122 variant bits set.

    Optional inputs make the bit layout deterministic in focused tests.  They
    are not accepted from API callers.
    """

    observed_ms = (
        int(time.time_ns() // 1_000_000)
        if timestamp_ms is None
        else int(timestamp_ms)
    )
    if not 0 <= observed_ms < (1 << 48):
        raise ValueError("uuid7_timestamp_out_of_range")

    random_bits = secrets.randbits(74) if entropy is None else int(entropy)
    if not 0 <= random_bits < (1 << 74):
        raise ValueError("uuid7_entropy_out_of_range")

    rand_a = random_bits >> 62
    rand_b = random_bits & ((1 << 62) - 1)
    value = (
        (observed_ms << 80)
        | (0x7 << 76)
        | (rand_a << 64)
        | (0b10 << 62)
        | rand_b
    )
    return UUID(int=value)


def canonical_traceparent(run_id: UUID) -> str:
    """Derive a stable W3C traceparent from one durable run identifier."""

    trace_hex = hashlib.sha256(
        f"awooop-runtime-trace:{run_id}".encode()
    ).hexdigest()[:32]
    span_hex = hashlib.sha256(
        f"awooop-runtime-root-span:{run_id}".encode()
    ).hexdigest()[:16]
    return f"00-{trace_hex}-{span_hex}-01"


def is_canonical_traceparent(value: str, *, run_id: UUID | None = None) -> bool:
    """Validate shape and, when supplied, binding to the durable run."""

    candidate = str(value or "").strip()
    if _TRACEPARENT_RE.fullmatch(candidate) is None:
        return False
    return run_id is None or candidate == canonical_traceparent(run_id)


def canonical_work_item_id(project_id: str, run_id: UUID) -> str:
    """Return the only generic work-item identity for one platform run."""

    project = str(project_id or "").strip()
    if _PROJECT_ID_RE.fullmatch(project) is None:
        raise ValueError("runtime_correlation_project_id_invalid")
    return f"platform-run:{project}:{run_id}"


def correlation_readback_for_run(
    project_id: str,
    run_id: UUID,
    trace_id: str | None,
) -> dict[str, str | None]:
    """Project stored trace truth plus its canonical run-bound work item."""

    stored_trace_id = None if trace_id is None else str(trace_id)
    return {
        "trace_id": stored_trace_id,
        "work_item_id": canonical_work_item_id(project_id, run_id),
        "correlation_status": (
            "canonical"
            if is_canonical_traceparent(stored_trace_id or "", run_id=run_id)
            else "legacy_or_invalid_trace"
        ),
    }


def correlation_for_run(project_id: str, run_id: UUID) -> RuntimeCorrelation:
    """Build the canonical public-safe correlation projection for a run."""

    return RuntimeCorrelation(
        run_id=run_id,
        trace_id=canonical_traceparent(run_id),
        work_item_id=canonical_work_item_id(project_id, run_id),
    )


def new_runtime_correlation(project_id: str) -> RuntimeCorrelation:
    """Allocate one new run root and all identifiers derived from it."""

    return correlation_for_run(project_id, new_uuid7())