"""
Tri-Source Truth Grounding Port Interface (Domain Core).
Protocol contract for cross-auditing CAD vector geometry, BBS rebar schedules,
and statutory tender BoQ / HSMT items.
"""

from __future__ import annotations

from pathlib import Path
from typing import Any, Protocol, runtime_checkable
from app.modules.takeoff.domain.inverse_bim_models import (
    BbsRebarScheduleItem,
    SolidTakeoffQuantities,
    TriSourceAuditReport,
)


@runtime_checkable
class TriSourceGroundingPort(Protocol):
    """Domain Port for Tri-Source Truth Grounding (Reconciliation Engine)."""

    def extract_bbs_schedule(
        self,
        source: str | Path,
    ) -> list[BbsRebarScheduleItem]:
        """Extract Bar Bending Schedule (BBS) rebar items from drawing sheet or schedule database."""
        ...

    def extract_hsmt_tender_items(
        self,
        source: str | Path,
    ) -> list[dict[str, Any]]:
        """Extract statutory tender BoQ / HSMT line items from spreadsheet or PDF."""
        ...

    def reconcile_tri_source(
        self,
        solids: SolidTakeoffQuantities,
        bbs_items: list[BbsRebarScheduleItem],
        hsmt_items: list[dict[str, Any]],
        project_name: str = "",
        package_name: str = "",
    ) -> TriSourceAuditReport:
        """Perform 3-way reconciliation cross-audit and flag any quantity/norm variance."""
        ...