"""Immutable staging-to-prod promotion authority helpers.

The staging release tag is the only authority for a production candidate.  This
module keeps the compact, deterministic subset of that tag which must be
re-attested immediately before any production mutation: the tag identity, the
resolved L2/L0 refs, and the final-pack tree hash.

It deliberately has no deployment or repository dependencies so both staging
tag emission and the production runner can use exactly the same canonical
representation.
"""

from __future__ import annotations

import hashlib
import json
from typing import Any, Mapping


PROMOTION_AUTHORITY_KIND = "staging-to-prod-promotion-authority"
PROMOTION_AUTHORITY_SCHEMA_VERSION = 1


def _required_text(value: object, label: str) -> str:
    normalized = str(value or "").strip()
    if not normalized:
        raise ValueError(f"missing {label}")
    return normalized


def _require_hex(value: object, label: str, length: int) -> str:
    normalized = _required_text(value, label).lower()
    if len(normalized) != length or any(ch not in "0123456789abcdef" for ch in normalized):
        raise ValueError(f"invalid {label}: expected {length}-character lowercase hex")
    return normalized


def _canonical_json(value: Mapping[str, Any]) -> bytes:
    return json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")


def promotion_authority_sha256(authority: Mapping[str, Any]) -> str:
    return hashlib.sha256(_canonical_json(authority)).hexdigest()


def build_promotion_authority(
    *,
    release_tag: object,
    tag_target_commit: object,
    executor_commit: object,
    upstream_ref: object,
    official_app_packs_ref: object,
    final_pack_hash: object,
) -> dict[str, Any]:
    """Build the exact candidate tuple that must survive staging-to-prod."""

    return {
        "schema_version": PROMOTION_AUTHORITY_SCHEMA_VERSION,
        "kind": PROMOTION_AUTHORITY_KIND,
        "candidate": {
            "release_tag": _required_text(release_tag, "release_tag"),
            "tag_target_commit": _require_hex(tag_target_commit, "tag_target_commit", 40),
            "executor_commit": _require_hex(executor_commit, "executor_commit", 40),
            "upstream_ref": _require_hex(upstream_ref, "upstream_ref", 40),
            "official_app_packs_ref": _require_hex(
                official_app_packs_ref,
                "official_app_packs_ref",
                40,
            ),
            "final_pack_hash": _require_hex(final_pack_hash, "final_pack_hash", 64),
        },
    }


def require_tag_promotion_authority(
    payload: Mapping[str, Any],
) -> tuple[dict[str, Any], str]:
    """Validate that a tag's serialized authority exactly matches tag facts."""

    raw_authority = payload.get("promotion_authority")
    if not isinstance(raw_authority, dict):
        raise ValueError("release tag is missing promotion_authority")
    executor = payload.get("executor")
    if not isinstance(executor, dict):
        raise ValueError("release tag is missing executor for promotion_authority")

    expected = build_promotion_authority(
        release_tag=payload.get("tag_name"),
        tag_target_commit=payload.get("tag_target_commit"),
        executor_commit=executor.get("commit"),
        upstream_ref=payload.get("upstream_commit"),
        official_app_packs_ref=payload.get("official_app_packs_commit"),
        final_pack_hash=payload.get("final_pack_hash"),
    )
    if raw_authority != expected:
        raise ValueError("release tag promotion_authority does not match tag candidate facts")

    declared_sha256 = _require_hex(
        payload.get("promotion_authority_sha256"),
        "promotion_authority_sha256",
        64,
    )
    if promotion_authority_sha256(raw_authority) != declared_sha256:
        raise ValueError("release tag promotion_authority_sha256 does not match promotion_authority")
    return expected, declared_sha256


def require_runtime_promotion_authority(
    *,
    expected_sha256: object,
    release_tag: object,
    tag_target_commit: object,
    executor_commit: object,
    upstream_ref: object,
    official_app_packs_ref: object,
    actual_final_pack_hash: object,
) -> dict[str, Any]:
    """Re-attest the tag authority against the exact materialized candidate."""

    expected = _require_hex(expected_sha256, "PROD_PROMOTION_AUTHORITY_SHA256", 64)
    authority = build_promotion_authority(
        release_tag=release_tag,
        tag_target_commit=tag_target_commit,
        executor_commit=executor_commit,
        upstream_ref=upstream_ref,
        official_app_packs_ref=official_app_packs_ref,
        final_pack_hash=actual_final_pack_hash,
    )
    actual = promotion_authority_sha256(authority)
    if actual != expected:
        raise ValueError(
            "materialized production candidate does not match tag-bound promotion authority"
        )
    return authority