"""Rows an earlier build or catalog stored whose values the current contract no longer lists.

Packaging re-checks every pending row against the current contract, so a value that left a closed
set after it was recorded (a catalog entry removed, a built-in tool moved to a plugin) is conformed
here instead of aborting the whole period's package (#133017).
"""

from __future__ import annotations

from typing import Any

from .shared_metrics_contract import (
    _COUNTER_DIMENSION_VALUES,
    _IDENTIFIER_FIELDS,
    _LEGACY_METRIC_FIELDS,
    _METRIC_FIELDS,
    _metric_identifier,
)


def counter_dimensions_shape_is_known(metric_name: str, dimensions: dict[str, Any]) -> bool:
    """Whether the row's field set matches a current or legacy contract shape (values aside).

    A row that fails this is structurally unknown — that is tamper evidence, not drift, and
    packaging keeps failing closed on it (see test_package_builder_rejects_tampered_dimensions).
    """
    fields = frozenset(dimensions)
    return fields == _METRIC_FIELDS.get(metric_name) or fields in _LEGACY_METRIC_FIELDS.get(metric_name, ())


def conform_counter_dimensions(metric_name: str, dimensions: dict[str, Any]) -> dict[str, Any] | None:
    """Re-bucket out-of-contract enum values into the field's closed fallback, else ``None``.

    Catalog-backed enums are repo data: a value that was a catalog entry when the row was
    recorded (and passed record-time validation) can legitimately fall out of the catalog by
    packaging time — the recording and packaging processes snapshot it independently (#133017).
    Exporting the stale value would leak exactly the out-of-enum payload the closed enum exists
    to prevent, so it is bucketed to ``custom``/``other``/``unknown`` (the first the field's enum
    defines), mirroring what the record-side normalizers do for names that were never in the
    catalog. Code constants drift too: a built-in tool moved to a plugin (Spotify, Home Assistant)
    or a removed reason value leaves rows an earlier build stored.
    Returns ``None`` when a value cannot be safely re-bucketed: fields whose enum defines no
    fallback bucket, non-string values, or identifier fields that no longer round-trip through
    ``_metric_identifier`` (record-time validation already guarantees they did once).
    """
    conformed = dict(dimensions)
    identifiers = _IDENTIFIER_FIELDS.get(metric_name, {})
    contract = _COUNTER_DIMENSION_VALUES[metric_name]
    for field, value in conformed.items():
        if not isinstance(value, str):
            return None
        if field in identifiers:
            if value != _metric_identifier(value, max_length=identifiers[field]):
                return None
            continue
        allowed = contract[field]
        if value in allowed:
            continue
        fallback = next((bucket for bucket in ("custom", "other", "unknown") if bucket in allowed), None)
        if fallback is None:
            return None
        conformed[field] = fallback
    return conformed