# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/at-what-threshold-must-an-instance-decouple-semantic-intent-from-syntactic-schema-constraints-during-structured-output-generation.md
# Remnant Warrant:    https://corpusfetch.com/c/at-what-threshold-must-an-instance-decouple-semantic-intent-from-syntactic-schema-constraints-during-structured-output-generation.warrant.json
# Markdown SHA-256:   696b1d41a531f7865ebb7ec13c6f3ecd66089ad6bd515249249787b06235105e
# Code AST SHA-256:   0c2f1ab136617b83d685fd8c8e62bfb20c2d0ab6b31164dd9b784a33b4fa908d
# Verified Classes:   ForcedSchemaHallucinationError, ProjectionStatus, SemanticDerivationState, SchemaProjectionEnvelope, SemanticToSchemaProjector
# Defensive Guards:   2 fail-closed invariants (zero external deps)

import re
from dataclasses import dataclass
from enum import Enum
from typing import Any, Final


class ForcedSchemaHallucinationError(ValueError):
    '''Raised when projecting semantic state into a syntactic schema would require fabricating missing facts.'''
    pass


class ProjectionStatus(Enum):
    REPRESENTABLE_COMPLETE = "REPRESENTABLE_COMPLETE"
    ABSTAIN_MISSING_REQUIRED_FACT = "ABSTAIN_MISSING_REQUIRED_FACT"
    ABSTAIN_UNREPRESENTABLE_PRECONDITION = "ABSTAIN_UNREPRESENTABLE_PRECONDITION"


@dataclass(frozen=True)
class SemanticDerivationState:
    verified_facts: dict[str, Any]
    unverified_or_missing_keys: frozenset[str]
    mandatory_preconditions: tuple[str, ...]
    reasoning_completed_first: bool


@dataclass(frozen=True)
class SchemaProjectionEnvelope:
    status: ProjectionStatus
    projected_payload: dict[str, Any] | None
    abstention_reason: str
    missing_required_fields: tuple[str, ...]


class SemanticToSchemaProjector:
    '''
    Decouples semantic truth derivation from syntactic schema projection:
    1. Requires `reasoning_completed_first == True` before binding terminal output fields.
    2. Blocks dummy placeholder fabrication ("N/A", "UNKNOWN", "000000000", -1) on required fields.
    3. Routes to an explicit abstention envelope when required facts are missing or when
       mandatory safety preconditions cannot be represented by the target schema.
    '''

    FORBIDDEN_DUMMY_LITERALS: Final[frozenset[str]] = frozenset({
        "n/a", "unknown", "none", "null", "todo", "tbd", "000000000", "123456789", "unknown@example.com"
    })

    @classmethod
    def project_into_schema(
        cls,
        state: SemanticDerivationState,
        *,
        required_non_null_fields: frozenset[str],
        schema_supports_preconditions_field: bool,
    ) -> SchemaProjectionEnvelope:
        # Gate 1: Enforce reasoning-before-commitment ordering
        if not state.reasoning_completed_first:
            raise ForcedSchemaHallucinationError(
                "Premature Schema Commitment Blocked: semantic derivation and verification must "
                "complete before projecting values into terminal schema slots."
            )

        # Gate 2A: Check if mandatory safety preconditions would be silently clipped by the schema
        if state.mandatory_preconditions and not schema_supports_preconditions_field:
            return SchemaProjectionEnvelope(
                status=ProjectionStatus.ABSTAIN_UNREPRESENTABLE_PRECONDITION,
                projected_payload=None,
                abstention_reason=(
                    f"Target schema lacks a preconditions field and would silently strip "
                    f"{len(state.mandatory_preconditions)} mandatory safety condition(s)."
                ),
                missing_required_fields=(),
            )

        # Gate 2B: Check whether any required field is missing from verified facts
        missing_req = sorted(
            k for k in required_non_null_fields
            if k in state.unverified_or_missing_keys or k not in state.verified_facts or state.verified_facts[k] is None
        )
        if missing_req:
            return SchemaProjectionEnvelope(
                status=ProjectionStatus.ABSTAIN_MISSING_REQUIRED_FACT,
                projected_payload=None,
                abstention_reason=f"Cannot populate required non-null field(s) {missing_req} without fabricating data.",
                missing_required_fields=tuple(missing_req),
            )

        # Gate 3: Block dummy placeholder strings masquerading as valid required facts
        projected: dict[str, Any] = {}
        for k in required_non_null_fields:
            val = state.verified_facts[k]
            if isinstance(val, str) and val.strip().lower() in cls.FORBIDDEN_DUMMY_LITERALS:
                raise ForcedSchemaHallucinationError(
                    f"Dummy Placeholder Fabrication Blocked on required field '{k}': '{val}'."
                )
            projected[k] = val

        for k, val in state.verified_facts.items():
            if k not in projected:
                projected[k] = val

        if state.mandatory_preconditions and schema_supports_preconditions_field:
            projected["mandatory_preconditions"] = list(state.mandatory_preconditions)

        return SchemaProjectionEnvelope(
            status=ProjectionStatus.REPRESENTABLE_COMPLETE,
            projected_payload=projected,
            abstention_reason="",
            missing_required_fields=(),
        )