#!/usr/bin/env python3
"""Honest four-tier timing contract for uncalibrated day/month/year claims."""

from __future__ import annotations

from typing import Any


def _tier(
    *,
    status: str,
    allowed_claims: list[str],
    prohibited_claims: list[str],
    note: str,
) -> dict[str, Any]:
    return {
        "status": status,
        "allowed_claims": allowed_claims,
        "prohibited_claims": prohibited_claims,
        "note": note,
    }


def _has_annual_series(source: dict[str, Any]) -> bool:
    annual_series = source.get("annual_series")
    if isinstance(annual_series, dict):
        years = annual_series.get("years")
        if isinstance(years, dict) and years:
            return True
        if isinstance(years, list) and years:
            return True
    if source.get("annual_tajika_series") or source.get("annual_chart") or source.get("solar_return"):
        return True
    return False


def build_timing_precision_contract(payload: dict[str, Any] | None = None) -> dict[str, Any]:
    source = payload if isinstance(payload, dict) else {}
    candidates = source.get("candidate_windows") if isinstance(source.get("candidate_windows"), list) else []
    triggers = source.get("exact_triggers") if isinstance(source.get("exact_triggers"), list) else []
    verified_window = source.get("verified_window") or source.get("broad_window")
    has_annual = _has_annual_series(source)
    year_status = "partial_verified" if has_annual else "blocked"
    return {
        "timing_precision": "candidate_day_window" if candidates else "broad_window_only",
        "claim_status": "exploratory_unvalidated",
        "verified_window": verified_window,
        "candidate_windows": candidates,
        "exact_triggers": triggers,
        "promotion_gate": {
            "status": "blocked",
            "required": "new_independently_labeled_day_level_holdout",
            "current_negative_controls_reusable_for_tuning": False,
        },
        "tiers": {
            "day": _tier(
                status="blocked",
                allowed_claims=[],
                prohibited_claims=["exact_day_event", "exact_clock_event", "dated_outcome_promise"],
                note="日级 holdout 未通过，日结论恒 blocked。",
            ),
            "week": _tier(
                status="parameter_sensitive",
                allowed_claims=["candidate_observation_window"],
                prohibited_claims=["exact_day_event", "guaranteed_weekly_outcome"],
                note="周级只可作为候选观察窗，不能升级为确定事件。",
            ),
            "month": _tier(
                status="parameter_sensitive",
                allowed_claims=["candidate_observation_window"],
                prohibited_claims=["exact_day_event", "guaranteed_monthly_outcome"],
                note="月级只可作为候选观察窗，不能升级为确定事件。",
            ),
            "year": _tier(
                status=year_status,
                allowed_claims=["annual_solar_return_structure"] if has_annual else [],
                prohibited_claims=["exact_day_event", "year_as_verified_event_calendar"],
                note=(
                    "年度返照系列存在时，年结构可标 partial_verified；仍禁止把年层写成已验证事件日历。"
                    if has_annual
                    else "缺少年度返照系列，年结论保持 blocked。"
                ),
            ),
        },
        "boundary": "候选日期未通过独立日级 holdout 验证，不能作为确定事件承诺；精确时间仅表示技术触发点。",
    }