"""IMP-33 u2 — AI fallback proposal schema.

Whitelisted proposal kinds (Stage 2 plan):
  - builder_options_patch     : zone/frame builder option overrides
  - partial_overrides         : Internal Region / Frame Slot content overrides
  - slot_mapping_proposal     : restructuring proposal (content unit mapping)

Forbidden output forms (rejected by validator):
  - mdx_text          (MDX read-only — `feedback_ai_isolation_contract`)
  - frame_id_change   (V4 rank-1 protected — `feedback_phase_z_spacing_direction`)
  - raw_html          (HTML structure is code-decided, not AI-generated)
  - raw_css           (same)
"""
from __future__ import annotations

from enum import Enum
from typing import Any

from pydantic import BaseModel, ConfigDict, Field, field_validator


class ProposalKind(str, Enum):
    BUILDER_OPTIONS_PATCH = "builder_options_patch"
    PARTIAL_OVERRIDES = "partial_overrides"
    SLOT_MAPPING_PROPOSAL = "slot_mapping_proposal"


FORBIDDEN_KINDS: frozenset[str] = frozenset(
    {"mdx_text", "frame_id_change", "raw_html", "raw_css"}
)


class AiFallbackProposal(BaseModel):
    """Single AI fallback proposal (output contract for u4 client)."""

    model_config = ConfigDict(extra="forbid")

    proposal_kind: ProposalKind
    payload: dict[str, Any] = Field(default_factory=dict)
    rationale: str = ""

    @field_validator("proposal_kind", mode="before")
    @classmethod
    def _reject_forbidden_kind(cls, value: Any) -> Any:
        if isinstance(value, str) and value in FORBIDDEN_KINDS:
            raise ValueError(
                f"proposal_kind={value!r} is forbidden (MDX/frame/raw HTML/CSS "
                "mutations are not permitted under IMP-33)."
            )
        return value