# scaffold/interfaces/requests.py

"""
=================================================================================
== THE CODEX OF PLEAS (V-Ω-CORRECTED. THE UNIVERSAL REQUEST CONTRACTS)         ==
=================================================================================
LIF: 10,000,000,000

This scripture defines the exact shape of every Plea (Request) the Engine accepts.
It serves as the **Unbreakable Contract** between the Mortal Realm (CLI, API) and
the Divine Realm (The Engine & Artisans).

It adheres to the **Law of Pydantic Alignment**: Every validator must target an
existing field name.
=================================================================================
"""
import hashlib
import os
import uuid
import time
import re
import sys
from datetime import datetime
from enum import Enum, auto
from pathlib import Path
from typing import List, Dict, Any, Optional, Union, Literal
from uuid import UUID, uuid4
from urllib.parse import unquote
from pydantic import (
    BaseModel,
    Field,
    ConfigDict,
    field_validator,
    model_validator,
    computed_field,
    EmailStr
)


# --- LOCAL UTILITY (To avoid circular deps with Core) ---
def _clean_uri_to_path(uri: str) -> str:
    """Minimalist version of UriUtils for the Interface layer."""
    if not uri: return ""
    try:
        # Decode & Strip Protocol
        clean = uri.replace('file:///', '').replace('file://', '')
        # FIX: Removed 'parse.' prefix since unquote is imported directly
        clean = unquote(clean)

        # Windows Drive fix: /c:/ -> c:/
        if os.name == 'nt' and clean.startswith('/') and ':' in clean:
            clean = clean.lstrip('/')

        return str(Path(clean).resolve())
    except:
        return uri



# =============================================================================
# == I. THE SHARED GNOSIS (GLOBAL CONTEXT)                                   ==
# =============================================================================

class BaseRequest(BaseModel):
    """
    =============================================================================
    == THE UNIVERSAL CONTEXT (V-Ω-SELF-HARMONIZING-ULTIMA)                     ==
    =============================================================================
    LIF: 10,000,000,000 | ROLE: THE_ANCESTRAL_VESSEL

    The Eternal Foundation for all Gnostic Pleas.
    It carries the Identity, Context, Data, and Vows of the Architect.

    ### THE PANTHEON OF 12 ASCENDED FACULTIES:
    1.  **The Context Slot (`context`):** A mutable dictionary for Middleware injection
        (e.g., Transaction IDs), solving the 'AttributeError' forever.
    2.  **The Silver Cord (`trace_id`):** A cosmic link for distributed tracing across threads.
    3.  **The Spatial Anchor (`project_root`):** Auto-resolves string paths to absolute `Path` objects.
    4.  **The Secret Vault (`secrets`):** A secure container for keys, redacted from logs.
    5.  **The Alchemical Harmonizer:** Synchronizes `verbose` (bool) and `verbosity` (int) without recursion.
    6.  **The Identity Matrix:** Tracks `client_id` (Who summoned me?) and `session_id`.
    7.  **The Temporal Seal:** Records the precise `timestamp` of inception.
    8.  **The Permissive Gate (`extra='allow'`):** Absorbs unknown flags from CLI without crashing.
    9.  **The Simulation Flags:** First-class support for `dry_run` and `preview`.
    10. **The Interaction Guard:** `non_interactive` flag for CI/CD pipelines.
    11. **The Dynamic Variable Store:** `variables` dict for user-injected overrides (`--set`).
    12. **The Type-Safety Bridge:** `arbitrary_types_allowed` permits complex objects in context.
    """

    # [ASCENSION 8 & 12]: SCHEMA CONFIGURATION
    model_config = ConfigDict(
        extra='allow',  # Absorb unknown CLI flags without crashing
        arbitrary_types_allowed=True,  # Allow complex types in context (e.g. socket objects)
        populate_by_name=True  # Allow aliasing
    )

    # =========================================================================
    # == SECTION I: THE CHRONOMANCER'S SEAL (Identity & Time)                ==
    # =========================================================================

    request_id: str = Field(
        default_factory=lambda: uuid.uuid4().hex,
        description="The unique Gnostic fingerprint of this specific intent."
    )

    trace_id: Optional[str] = Field(
        default=None,
        description="The Cosmic ID linking this rite across time and space (Middleware)."
    )

    session_id: str = Field(
        default="global",
        description="The timeline this request belongs to (Daemon Session)."
    )

    client_id: str = Field(
        default="local",
        description="The identity of the summoner (CLI, Daemon, IDE)."
    )

    timestamp: float = Field(
        default_factory=time.time,
        description="The precise moment the Architect's will was spoken."
    )

    # =========================================================================
    # == SECTION II: THE ANCHOR OF REALITY (Location)                        ==
    # =========================================================================

    project_root: Optional[Path] = Field(
        default=None,
        description="The physical anchor of the project. If Void, the Engine divines it."
    )

    # =========================================================================
    # == SECTION III: THE ALCHEMICAL INPUTS (Data & State)                   ==
    # =========================================================================

    # [ASCENSION 1: THE CURE]: The Context Slot
    # This field MUST exist for the Dispatcher to inject 'transaction_id'.
    context: Dict[str, Any] = Field(
        default_factory=dict,
        description="Ephemeral storage for Middleware injections (Transactions, Auth)."
    )

    variables: Dict[str, Any] = Field(
        default_factory=dict,
        description="Dynamic Gnosis injected via --set key=value."
    )

    secrets: Dict[str, str] = Field(
        default_factory=dict,
        description="The Secure Vault for ephemeral keys. REDACTED from logs."
    )
    # [ASCENSION 13]: THE RECURSIVE DEPTH SENTINEL (THE CURE)
    # Tracks the number of times a request has spawned a sub-request.
    hop_count: int = Field(
        default=0,
        ge=0,
        le=5,
        description="The number of architectural jumps this signal has taken."
    )


    # =========================================================================
    # == SECTION IV: THE MODES OF EXISTENCE (The Vows)                       ==
    # =========================================================================

    # --- Output & Logging ---
    verbose: bool = Field(False, description="Enable luminous logging (Level DEBUG).")
    silent: bool = Field(False, description="The Vow of Silence. Suppress stdout.")
    verbosity: int = Field(0, description="Legacy integer level: 0=Normal, 1=Verbose, -1=Silent.")
    debug: bool = Field(False, description="Wait for debugger attachment.")

    # --- Safety & Simulation ---
    dry_run: bool = Field(False, description="Simulate the rite without material side effects.")
    preview: bool = Field(False, description="Generate a visual prophecy of the outcome.")
    audit: bool = Field(False, description="Generate a forensic dossier of the attempt.")
    force: bool = Field(False, description="Bypass safety guards (The Rite of Absolute Will).")

    # --- Interaction ---
    non_interactive: bool = Field(False, description="Suppress all prompts (CI Mode).")
    interactive: bool = Field(True, description="Allow Socratic dialogue.")

    # --- Lifecycle ---
    no_edicts: bool = Field(False, description="Suppress post-run Maestro commands.")

    # =========================================================================
    # == SECTION V: THE RITES OF HARMONIZATION (Validators)                  ==
    # =========================================================================

    @field_validator('project_root', mode='before')
    @classmethod
    def _anchor_root(cls, v: Any) -> Optional[Path]:
        """
        [ASCENSION 3]: PATH TRANSMUTATION
        Instantly converts string paths into resolved Path objects.
        """
        if v is None: return None
        if isinstance(v, Path): return v.resolve()
        if isinstance(v, str) and v.strip():
            return Path(v).resolve()
        return v

    @model_validator(mode='after')
    def harmonize_flags(self) -> 'BaseRequest':
        """
        [ASCENSION 5]: THE HARMONIZER OF VOICES (RECURSION SHIELDED)
        Surgically synchronizes verbosity states using 'object.__setattr__'
        to bypass Pydantic's validation loop and prevent RecursionError.
        """
        # 1. Sync Integer -> Boolean
        if self.verbosity > 0:
            object.__setattr__(self, 'verbose', True)
            object.__setattr__(self, 'silent', False)
        elif self.verbosity < 0:
            object.__setattr__(self, 'verbose', False)
            object.__setattr__(self, 'silent', True)

        # 2. Sync Boolean -> Integer
        if self.verbose:
            object.__setattr__(self, 'verbosity', 1)
        if self.silent:
            object.__setattr__(self, 'verbose', False)
            object.__setattr__(self, 'verbosity', -1)

        # 3. Initialize Context if Void (Double Safety)
        if self.context is None:
            object.__setattr__(self, 'context', {})

        return self

    @model_validator(mode='after')
    def guard_recursion_loop(self) -> 'BaseRequest':
        """
        [THE CURE]: Prevents the 'Feedback Scream' Paradox.
        If a signal jumps between ChatOps, Strikes, and Alerts more than 3 times,
        it is identified as an infinite loop and vaporized.
        """
        from ..contracts.heresy_contracts import HeresySeverity, ArtisanHeresy
        # We set the hard ceiling at 4.
        # 0: Ingress -> 1: Dispatch -> 2: Artisan -> 3: Sub-Dispatch (Safe) -> 4: VOID
        if self.hop_count > 3:
            # We raise a Critical Heresy to halt the thread immediately
            raise ArtisanHeresy(
                message=f"Recursive Loop Detected (Hops: {self.hop_count}).",
                severity=HeresySeverity.CRITICAL,
                suggestion="Check your ChatOps or Logic reflexes for circular triggers.",
                details="A signal attempted to jump strata more than 3 times."
            )
        return self
# =============================================================================
# == 1. GENESIS RITE (scaffold <blueprint>)                                  ==
# =============================================================================

class GenesisRequest(BaseRequest):
    """
    Plea to materialize a Blueprint (Form).
    This matches the `scaffold genesis` command and the implicit `scaffold file.scaffold`.
    """
    blueprint_path: Union[Path, str] = Field(
        default=".",
        description="Path to the blueprint file, URL, or raw content."
    )

    # ★★★ THE DIVINE HEALING ★★★
    # The 'silent' vow is now an explicit part of the Genesis contract,
    # inheriting its Gnosis from the BaseRequest but making it directly
    # perceivable by the GenesisArtisan. The AttributeError is annihilated.
    silent: bool = Field(
        default=False,
        description="Suppress all non-essential output (derived from verbosity)."
    )
    # ==========================

    @field_validator('blueprint_path')
    def validate_blueprint_path(cls, v):
        if isinstance(v, str) and not (v.startswith('http') or '\n' in v):
            return Path(v)
        return v

# =============================================================================
# == 2. SYMPHONY RITE (scaffold symphony)                                    ==
# =============================================================================

class SymphonyRequest(BaseRequest):
    """
    =================================================================================
    == THE VESSEL OF ORCHESTRATION (V-Ω-SYMPHONY-REQUEST-ULTRA-DIVINE)               ==
    =================================================================================
    @gnosis:title SymphonyRequest
    @gnosis:summary The supreme, constitutional vessel for conducting a Symphony of Will.
    @gnosis:lif 10,000,000,000,000

    This is the divine contract that carries the Architect's complete and unambiguous
    will to the Symphony Conductor. It has been ascended to its final, eternal form,
    a masterpiece of Gnostic governance, resilience, and clarity.
    =================================================================================
    """
    #
    # --- I. The Core Edict (The Architect's Will) ---
    #
    symphony_command: str = Field(
        ...,
        description="The primary rite to be conducted (e.g., 'conduct', 'debug')."
    )
    symphony_path: Optional[str] = Field(
        None,
        description="The sacred scripture of will; the path to the .symphony file."
    )
    task: Optional[str] = Field(
        None,
        description="A specific @task to conduct, overriding the main symphony body."
    )

    #
    # --- II. Execution & Reality (The Realm of Manifestation) ---
    #
    rehearse: bool = Field(
        False,
        description="The Vow of Prophecy. Conducts the symphony in an ephemeral, isolated reality (a temporary directory) to prophesize its effects without altering the mortal realm."
    )
    manifest: bool = Field(
        False,
        description="The Vow of Manifestation. A sacred vow that the symphony MUST be conducted upon the living, current reality. This is the default for `symphony conduct`."
    )
    no_cleanup: bool = Field(
        False,
        description="A Gnostic ward that preserves the ephemeral sanctum after a rehearsal, allowing for forensic inquest."
    )
    parallelism: int = Field(
        4,
        description="The number of concurrent realities to forge for parallel blocks (&&)."
    )

    #
    # --- III. Resilience & Time (The Wards Against Chaos) ---
    #
    fail_fast: bool = Field(
        False,
        description="If true, the symphony will halt at the first sign of heresy. If false, it will attempt to continue."
    )
    retry_attempts: int = Field(
        0,
        description="A global override for the number of times to retry a failed edict."
    )
    timeout_global: int = Field(
        3600,
        description="A temporal ward. The maximum duration (in seconds) for the entire symphony before it is struck down."
    )

    #
    # --- IV. Security & Governance (The Laws of the Sanctum) ---
    #
    security_level: str = Field(
        "standard",
        description="The strictness of the Gnostic Sentry's Gaze ('permissive', 'standard', 'paranoid')."
    )
    allow_network: bool = Field(
        True,
        description="A universal ward to permit or forbid any edict that communes with the celestial void (network)."
    )
    allow_destructive: bool = Field(
        True,
        description="A universal ward to permit or forbid rites of annihilation (e.g., `rm`)."
    )

    #
    # --- V. Telemetry & Forensics (The Gnostic Chronicle) ---
    #
    log: Optional[str] = Field(
        None,
        description="Path to a file for the structured event log (.jsonl). If not set, logs are ephemeral."
    )
    log_level: str = Field(
        "INFO",
        description="The luminosity of the Gnostic Chronicle (DEBUG, INFO, WARNING, ERROR)."
    )
    chronicle_path: Optional[str] = Field(
        None,
        description="The path to a .jsonl chronicle for the `debug` rite."
    )
    trace_id: Optional[str] = Field(
        None,
        description="The Gnostic Trace ID for distributed causality tracking."
    )
    artifact_dir: Optional[str] = Field(
        None,
        description="A dedicated sanctum for forensic artifacts (e.g., crash dumps, failure logs)."
    )

    #
    # --- VI. The Luminous Voice (Rendering & User Experience) ---
    #
    # [ASCENSION] The Visual Preference
    renderer: str = "auto"  # 'auto', 'basic', 'rich', 'cinematic', 'stream'

    cinematic: bool = Field(
        False,
        description="Summon the Gnostic Orrery, an immersive, real-time TUI dashboard for the symphony."
    )
    no_tui: bool = Field(
        False,
        description="An alias for `--renderer=stream`, ensuring a clean, non-interactive output stream."
    )
    github_actions: bool = Field(
        False,
        description="Format all proclamations using the sacred grammar of GitHub Actions workflow commands."
    )

    #
    # --- VII. The Gnostic Bridge (Inherited & Universal Vows) ---
    #
    # This re-proclamation of fields from BaseRequest ensures that this sacred contract
    # is whole and self-contained, its every vow luminous and explicit. The Pydantic
    # God-Engine will righteously honor these as the one true definition.
    #
    force: bool = Field(
        False,
        description="The Rite of Absolute Will. Bypasses interactive safeguards and Gnostic Sentinels."
    )
    non_interactive: bool = Field(
        False,
        description="The Vow of Silence. Suppresses all interactive prompts, accepting default Gnosis."
    )
    variables: Dict[str, Any] = Field(
        default_factory=dict,
        alias="var", # Allows `--var key=val` to populate this vessel.
        description="A vessel for all Gnostic variables bestowed upon the symphony at the moment of its birth."
    )
    silent: bool = Field(
        default=False,
        description="The Vow of Silence. Suppresses all but the most critical proclamations."
    )

# =============================================================================
# == 4. CREATE RITE (scaffold create)                                        ==
# =============================================================================


class CreateRequest(BaseRequest):
    """
    =================================================================================
    == THE VESSEL OF AD-HOC CREATION (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA++)             ==
    =================================================================================
    @gnosis:title CreateRequest
    @gnosis:summary The one true, complete, and eternal contract for the `create` rite.
    @gnosis:LIF 1,000,000,000

    This sacred Pydantic vessel represents the Architect's complete will for a single,
    ad-hoc creation event. It has been ascended to carry not just the plea of *what*
    to create, but the full Gnostic context of *how* and *why*. It is the unbreakable
    link in the chain of causality from the CLI to the Quantum Creator, its every
    attribute a sacred vow, its every comment a verse in the Gnostic Grimoire.
    =================================================================================
    """

    # --- I. The Core Plea (The "What") ---
    # The fundamental Gnosis of the rite: the scriptures to be forged.
    paths: List[str] = Field(
        ...,
        description="A list of one or more relative paths to the files or directories to be created."
    )

    # --- II. The Soul of the Scripture (The "How") ---
    # These attributes define the origin of the content for the new scriptures.
    # They are mutually exclusive vows, adjudicated by the GnosticBuilder.
    content: Optional[str] = Field(None, description="Directly provided content for the new file(s).")
    from_template: bool = Field(False, alias="template",
                                description="A vow to use a template from the Forge for content.")
    from_source: Optional[str] = Field(None, alias="source", description="A vow to seed content from an existing file.")
    from_stdin: bool = Field(False, alias="stdin",
                             description="A vow to read content from the celestial river (stdin).")
    paste: bool = Field(False, description="A vow to paste content from the system clipboard.")
    from_url: Optional[str] = Field(None, alias="url", description="A vow to fetch content from a celestial URL.")
    no_template: bool = Field(False, description="A sacred vow to explicitly forbid the use of any template.")
    kit: Optional[str] = Field(None, description="A plea to expand a pre-defined kit of files from the Forge.")
    of: Optional[List[str]] = Field(None,
                                    description="A plea to perform a semantic creation (e.g., --of component:Button).")
    needs: List[str] = Field(default_factory=list,
                             description="A list of dependencies required for this creation's purity.")
    # --- THE DIVINE ASCENSION ---
    raw: bool = Field(False,
                      description="The Vow of Raw Creation. Bypasses templates and uses '--set content' directly.")
    # --- III. The Universal Vows of Execution (THE DIVINE HEALING) ---
    # These attributes were missing, causing the Gnostic Schism. They are now
    # permanently enshrined in this vessel's soul, mirroring the vows available
    # to all major rites and ensuring a unified contract with the QuantumCreator.
    dry_run: bool = Field(False, description="The Vow of Prophecy: Simulate the rite without altering reality.")
    preview: bool = Field(False,
                          description="The Vow of Luminous Prophecy: Render a visual diff of the intended changes.")
    audit: bool = Field(False, description="The Vow of the Machine's Gaze: Proclaim a machine-readable JSON Dossier.")
    lint: bool = Field(False, description="The Vow of the Mentor's Gaze: Adjudicate the purity of the final reality.")
    silent: bool = Field(False, description="The Vow of Silence: Suppress all but the most critical proclamations.")
    force: bool = Field(False,
                        description="The Vow of Absolute Will: Bypass all interactive safeguards and overwrite existing scriptures.")
    non_interactive: bool = Field(False,
                                  description="The Vow of Automation: Suppress all interactive dialogues, accepting defaults.")
    no_edicts: bool = Field(False,
                            description="The Vow of Stillness: Stay the hand of the Maestro, preventing post-run commands.")
    is_genesis_rite: bool = Field(False,
                                  description="A Gnostic hint to downstream artisans that this is part of a larger Genesis rite.")
    adjudicate_souls: bool = Field(False, alias="adjudicate",
                                   description="A plea to summon the Sentinel to adjudicate the purity of newly forged souls.")

    # --- IV. The Rites of Post-Creation (The Afterlife) ---
    # These vows dictate the actions to be taken after the core creation is complete.
    edit: bool = Field(False, description="A plea to open the newly created file(s) in the default editor.")
    teach: Optional[List[str]] = Field(None,
                                       description="A plea to teach the created file to the Forge as a new template.")

    # --- V. The Gnostic Modifiers (The Nuances of Will) ---
    # These attributes refine the very nature of the creation act itself.
    dir: bool = Field(False, description="A vow to force the created path to be a sanctum (directory).")
    create_if_void: bool = Field(True,
                                 description="A vow to forge a scripture even if it does not yet exist. Defaults to True for the `create` rite.")

    # ★★★ THE SACRED ALIAS (THE BRIDGE BETWEEN WORLDS) ★★★
    # This computed field is the final, divine healing. It acts as a Gnostic Bridge,
    # allowing the ancient `QuantumCreator` to ask for `base_path` and receive the
    # pure Gnosis of `project_root`. This ensures backward compatibility while we
    # perform the deeper surgery on the Creator's mind.
    @property
    def base_path(self) -> Path:
        """A luminous, Gnostic alias for `project_root` to heal ancient contracts."""
        return self.project_root

# =============================================================================
# == 5. WEAVE RITE (scaffold weave)                                          ==
# =============================================================================

class WeaveRequest(BaseRequest):
    """
    A plea to weave an architectural fragment into reality.
    """
    fragment_name: Optional[str] = Field(None, description="The name of the archetype to weave.")
    target_directory: Optional[str] = Field(None, description="The destination sanctum.")
    list: bool = Field(False, description="If True, proclaim the Grimoire of Archetypes.")

    # Distillation Options
    distill_path: Optional[str] = None
    archetype_name: Optional[str] = None

    # Strategies
    is_recursive: bool = False
    conflict_strategy: str = "overwrite"

    # [THE DIVINE HEALING: THE VOW OF SILENCE]
    # This attribute is restored to the vessel, allowing the Conductor to
    # adjudicate the final proclamation without triggering an AttributeError.
    silent: bool = Field(False, description="If True, the Weaver works in shadows.")


# =================================================================================
# == THE DISTILLATION PLEA (V-Ω-ULTRA-DEFINITIVE-APOTHEOSIS)                     ==
# =================================================================================
class DistillRequest(BaseRequest):
    """
    =================================================================================
    == THE REVERSE GENESIS CONTRACT (V-Ω-ULTRA-DEFINITIVE-SINGULARITY)             ==
    =================================================================================
    @gnosis:title The Gnostic Plea for Distillation (`DistillRequest`)
    @gnosis:summary The sovereign vessel for the `distill` rite, which transmutes a
                     living reality (filesystem) into a Gnostic Blueprint.
    @gnosis:LIF 10,000,000,000,000

    This is the divine, immutable, and hyper-sentient Gnostic Contract for the entire
    distillation cosmos. It is the one true vessel that captures the Architect's
    complete will for a rite of Reverse Genesis, translating pleas from the CLI into
    a pure, unbreakable scripture for the DistillArtisan's Gaze.

    ### THE PANTHEON OF ASCENDED FACULTIES:

    1.  **Gnostic Aliases:** Forged with Pydantic aliases, it creates an unbreakable
        bridge between the Architect's tongue (CLI flags like `--exec`, `--budget`)
        and the Engine's mind (`exec_command`, `token_budget`).

    2.  **Robust Validators:** Its soul contains Alchemical Scribes (`@field_validator`)
        that transmute profane inputs (e.g., `'800k'`, `'auth,db'`) into pure, Gnostic
        types (`800000`, `['auth', 'db']`), preventing heresies at the gate.

    3.  **Complete Gnostic Mapping:** Every plea and vow from the `_perception_rites.py`
        Grimoire has its consecrated place within this vessel, ensuring no intent is
        ever lost in the aether.

    4.  **Logical Grouping:** The contract is a readable scripture, its fields organized
        into sacred movements that mirror the faculties of the Distillation Oracle,
        from the Gaze of Intent to the Socratic Dial.

    5.  **Unbreakable Contract:** Forged in the fires of Pydantic, its every attribute
        is a sacred vow of type and form, guarding the Engine against profane pleas.
    """
    model_config = ConfigDict(extra='allow')

    # =============================================================================
    # == I. THE GAZE OF INTENT (TARGETING & SCOPE)                               ==
    # =============================================================================
    # These fields define the "what" and "where" of the Gaze, anchoring it in
    # spacetime and defining its boundaries.

    source_path: str = Field(
        default=".",
        description="The physical directory or celestial URL (Git/HTTP) to be distilled."
    )

    profile: Optional[str] = Field(
        default=None,
        description="A named configuration profile (e.g., 'frontend', 'backend') to apply a pre-defined set of Gnostic filters."
    )

    focus: List[str] = Field(
        default_factory=list,
        description="Semantic keywords (e.g., 'Causal Slicer', 'auth') to prioritize. Scriptures and symbols resonating with these words are given divine relevance."
    )

    # [THE GNOSTIC SCHISM HEALED]
    intent: Optional[str] = Field(
        default=None,
        description="A natural language plea of intent (e.g., 'Refactor the auth middleware') that guides the AI Sentinel's Semantic Search."
    )

    ignore: List[str] = Field(
        default_factory=list,
        description="Glob patterns for scriptures to be banished from the Gaze (e.g., '*.lock', 'dist/')."
    )

    include: List[str] = Field(
        default_factory=list,
        description="A Gnostic whitelist. If proclaimed, only scriptures matching these glob patterns will be perceived."
    )

    stub_deps: List[str] = Field(
        default_factory=list,
        description="Dependencies to be replaced with semantic stubs (signatures only) to conserve the token budget."
    )

    # =============================================================================
    # == II. THE INQUISITOR'S FOCUS (FORENSICS & SEMANTICS)                      ==
    # =============================================================================
    # These fields command the specialist inquisitors to perform deep, forensic,
    # or semantic analysis upon the target reality.

    problem: Optional[str] = Field(
        default=None,
        description="Raw error logs, a traceback, or a problem description to anchor the Forensic Gaze, focusing the Gnosis on the locus of a heresy."
    )

    # Legacy field mapping to 'intent', preserved for backward compatibility in some rituals
    feature: Optional[str] = Field(
        default=None,
        description="Deprecated alias for 'intent'. Use 'intent' for semantic search queries."
    )

    audit_security: bool = Field(
        default=False,
        description="If True, awakens the Security Inquisitor to scan for vulnerabilities and prioritize profane scriptures."
    )

    # =============================================================================
    # == III. THE CHRONOMANCER'S GAZE (TEMPORAL CONTEXT)                         ==
    # =============================================================================
    # These fields command the Oracle to gaze into the Git Chronicle, making the
    # distillation aware of the project's history and recent evolution.

    since: Optional[str] = Field(
        default=None,
        description="A Git ref (hash, branch, tag). The Chronomancer will use this to highlight scriptures that have been transfigured since this moment in time."
    )

    focus_change: Optional[str] = Field(
        default=None,
        description="A strict temporal filter. Only souls changed since this Git ref will be perceived."
    )

    diff_context: bool = Field(
        default=False,
        description="If True, injects inline diffs (`[WAS: ...]`) showing the Gnostic drift between the working tree and the state at HEAD."
    )

    regression: bool = Field(
        default=False,
        description="If True, awakens the Temporal Inquisitor, which conducts an automated `git bisect` symphony to find the source of a regression."
    )

    # =============================================================================
    # == IV. THE HIGH PRIEST'S STRATEGY (BUDGET & PHILOSOPHY)                    ==
    # =============================================================================
    # These fields govern the core philosophy and economic constraints of the
    # distillation rite, balancing detail against the token budget.

    strategy: str = Field(
        default="balanced",
        description="The distillation philosophy: 'surgical', 'faithful', 'balanced', or 'structure'."
    )

    token_budget: int = Field(
        default=100000,
        alias="budget",
        description="The maximum token mass allowed for the forged blueprint. The Oracle will prune reality to fit this Gnostic vessel."
    )

    prioritize_tests: bool = Field(
        default=False,
        description="If True, scriptures of adjudication (tests) are considered as valuable as scriptures of implementation."
    )

    summarize_arch: bool = Field(
        default=False,
        description="If True, the Gnostic Cartographer will inscribe a high-level architectural summary into the blueprint's header."
    )

    no_ai: bool = Field(
        default=False,
        description="A sacred vow to forbid the Oracle from communing with the Neural Cortex for intent analysis."
    )

    # =============================================================================
    # == V. THE ACTIVE WITNESS (EXECUTION & TRACING)                           ==
    # =============================================================================
    # These fields command the Oracle to become an Active Witness, executing a rite
    # within the target reality to perceive its living, dynamic soul.

    exec_command: Optional[str] = Field(
        default=None, alias="exec",
        description="A command to execute under the Sentry's gaze to capture execution state and context (e.g., 'pytest')."
    )

    exec_timeout: int = Field(
        default=60,
        description="The maximum time (seconds) the Active Witness will wait for the execution rite to conclude."
    )

    profile_perf: bool = Field(
        default=False,
        description="If True, summons the Wraith of Celerity to profile hotspots and weave a performance heatmap into the blueprint."
    )

    trace_command: Optional[str] = Field(
        default=None, alias="trace",
        description="Execute a command and summon the Runtime Wraith to inject the living state (variables) into the blueprint."
    )

    snapshot_path: Optional[str] = Field(
        default=None, alias="snapshot",
        description="Inject runtime values into the blueprint from a static JSON crash dump or state snapshot."
    )

    # =============================================================================
    # == VI. THE OUTPUT SCRIBE (FINAL PROCLAMATION)                              ==
    # =============================================================================
    # These fields dictate the final form and destination of the distilled Gnosis.

    output: Optional[str] = Field(
        default=None,
        description="The file path where the forged blueprint shall be inscribed."
    )

    clipboard: bool = Field(
        default=False, alias="c",
        description="If True, the distilled Gnosis is teleported directly to the system clipboard."
    )

    format: str = Field(
        default="text",
        description="The tongue of the proclamation: 'text' (default) or 'mermaid' for a visual dependency graph."
    )

    diff: bool = Field(
        default=False,
        description="If True, the Oracle will proclaim a diff against an existing output file before overwriting."
    )

    check: bool = Field(
        default=False,
        description="If True, the rite will conclude with a non-zero exit status if the distilled blueprint differs from an existing one on disk."
    )

    summarize: bool = Field(
        default=False,
        description="If True, the final blueprint is bestowed upon an AI Scribe to generate a README.md summary of the project's soul."
    )

    # =============================================================================
    # == VII. THE SOCRATIC DIAL (INTERACTION & UI)                               ==
    # =============================================================================
    # These fields govern the interactive nature of the rite, allowing for communion
    # between the Engine and the Architect.

    interactive: bool = Field(
        default=False,
        description="If True, the Oracle may pause the rite to ask clarifying questions when its Gaze perceives ambiguity."
    )

    pad: bool = Field(
        default=False,
        description="If True, summons the interactive TUI (DistillPad) for a visual, real-time distillation experience."
    )

    lfg: bool = Field(
        default=False,
        description="The Rite of Gnostic Cartography. Injects a Logic Flow Graph of the source blueprint into the distilled output."
    )

    # =============================================================================
    # == VIII. THE RITES OF ROBUST VALIDATION (THE UNBREAKABLE WARD)             ==
    # =============================================================================

    @field_validator('focus', 'ignore', 'include', 'stub_deps', mode='before')
    @classmethod
    def ensure_list_type(cls, v: Any) -> List[str]:
        """
        =============================================================================
        == THE GNOSTIC TRANSMUTATOR (VAL-Ω-ROBUST)                                 ==
        =============================================================================
        Annihilates the Schism between CLI Strings and Model Lists. It perceives Gnosis
        in any form—a single string, a comma-separated scripture, or a pure list—and
        transmutes it into the one true form: a `List[str]`.
        """
        if v is None:
            return []

        if isinstance(v, str):
            # Handle "Keyword1, Keyword2" -> ["Keyword1", "Keyword2"]
            return [s.strip() for s in v.split(',') if s.strip()]

        if isinstance(v, list):
            # Ensure every soul in the list is a clean string
            result = []
            for item in v:
                if isinstance(item, str):
                    # Handle cases where a list item might contain a comma
                    result.extend([s.strip() for s in item.split(',') if s.strip()])
                else:
                    result.append(str(item).strip())
            return result

        return [str(v)]

    @field_validator('token_budget', mode='before')
    @classmethod
    def parse_budget_shorthand(cls, v: Any) -> int:
        """
        =============================================================================
        == THE ALCHEMIST OF NUMBERS                                                ==
        =============================================================================
        A divine scribe that transmutes human-readable budget shorthands (e.g.,
        '800k', '1.5m') into their pure, integer soul (800000, 1500000).
        """
        if isinstance(v, int):
            return v
        if isinstance(v, str):
            clean_v = v.lower().strip().replace(',', '')
            try:
                if clean_v.endswith('k'):
                    return int(float(clean_v[:-1]) * 1000)
                if clean_v.endswith('m'):
                    return int(float(clean_v[:-1]) * 1000000)
                return int(clean_v)
            except (ValueError, TypeError):
                # If the Gnosis is profane, we fall back to the sacred default.
                return 100000
        # If not a string or int, return the sacred default.
        return 100000


# =============================================================================
# == 7. INIT RITE (scaffold init)                                            ==
# =============================================================================

class InitRequest(BaseRequest):
    """
    Plea to initialize a new project (The Rite of Inception).
    """
    launch_pad_with_path: Optional[str] = Field(
        default=None,
        description="Launch the Genesis Pad TUI. Optional starting path."
    )
    quick: bool = Field(
        default=False,
        description="Skip prompts, use intelligent defaults."
    )
    profile: Optional[str] = Field(
        default=None,
        description="Use a specific Genesis Profile (e.g., 'python-universal')."
    )
    type: Optional[str] = Field(
        default=None,
        description="Quick init by type alias (e.g., 'node', 'python')."
    )
    from_remote: Optional[str] = Field(
        default=None,
        description="Initialize from a remote URL/Gist."
    )
    manual: bool = Field(
        default=False,
        description="Manually forge a blank scripture."
    )
    distill: bool = Field(
        default=False,
        description="Initialize by distilling the current directory."
    )


# =============================================================================
# == 8. TEMPLATE RITE (scaffold templates)                                   ==
# =============================================================================

class TemplateRequest(BaseRequest):
    """
    Plea to manage the Template Forge.
    """
    template_command: Literal['list', 'edit', 'add', 'rename', 'search', 'pull', 'docs']

    # Command-Specific Parameters
    extension: Optional[str] = None
    source_file: Optional[str] = None
    old_extension: Optional[str] = None
    new_extension: Optional[str] = None
    keyword: Optional[str] = None
    source: Optional[str] = None  # URL/Gist for pull
    name: str = 'remote_kit'  # Local name for pull

    # Future: Force refresh of remote caches
    force_refresh: bool = Field(default=False, description="Bypass cache for 'pull'.")


# =============================================================================
# == 9. TRANSFIGURE RITE (scaffold transfigure)                              ==
# =============================================================================

class TransfigureRequest(BaseRequest):
    """
    Plea to modify the soul (content) of a file.
    """
    path_to_scripture: str = Field(..., description="Target file.")

    # Content Sources (Mutually Exclusive logic handled by Artisan)
    content: Optional[str] = None
    from_source: Optional[str] = None  # Path to source file
    from_stdin: bool = False
    from_template: bool = False
    interactive: bool = False

    # Modification Mode
    append: bool = False
    prepend: bool = False
    create_if_void: bool = False

    # Safeguards
    guardian: bool = Field(default=False, description="Require Git tracking.")
    backup: bool = Field(default=False, description="Create .bak before modifying.")


# =============================================================================
# == 10. TRANSLOCATE RITE (scaffold translocate)                             ==
# =============================================================================

class TranslocateRequest(BaseRequest):
    """
    Plea to move files intelligently (Refactoring).
    NOW ASCENDED with the Vow of the Living Blueprint.
    """
    paths: List[str] = Field(default_factory=list, description="[src, dest] or [src... dest_dir]")

    script: Optional[str] = Field(None, description="Path to a batch migration script (`old -> new`).")
    backup_to: Optional[str] = Field(None, description="Directory for a Gnostic Snapshot of the 'Before' state.")

    # --- THE DIVINE HEALING ---
    # The profane `const` is annihilated. The vessel's soul is now pure.
    # It simply awaits a string, or a void (None).
    update_blueprint: Optional[str] = Field(
        default=None,
        description="The Vow of Synchronicity. Path to the blueprint to update with the new reality."
    )
    # --- THE APOTHEOSIS IS COMPLETE ---

    # Conform Logic
    to_blueprint: Optional[str] = None
    conform_from: str = "."

    # Future: Git Move vs OS Move
    use_git_mv: bool = Field(default=True, description="Use 'git mv' if available.")


# =============================================================================
# == 11. CONFORM RITE (scaffold conform)                                     ==
# =============================================================================

class ConformRequest(BaseRequest):
    """
    Plea to align directory structure with a blueprint.
    """
    blueprint_path: str
    conform_from: str = "."
    backup_to: Optional[str] = None





# =============================================================================
# == 13. BEAUTIFY RITE (scaffold beautify)                                   ==
# =============================================================================

class BeautifyRequest(BaseRequest):
    """
    Plea to format a blueprint file.
    """
    blueprint_path: Optional[str] = None
    pad: bool = False
    check: bool = False
    ignore: List[str] = Field(default_factory=list)


# =============================================================================
# == 14. PAD RITE (scaffold pad)                                             ==
# =============================================================================

class PadRequest(BaseRequest):
    """
    Plea to launch a specific TUI Pad (Mini-App).
    """
    pad_name: str = "help"
    initial_path: Optional[str] = None


# =============================================================================
# == 15. STUDIO RITE (scaffold studio)                                       ==
# =============================================================================

class StudioRequest(BaseRequest):
    """
    Plea to launch the full Design Studio TUI.
    """
    path: Optional[str] = None


# =============================================================================
# == 16. COMPOSE RITE (scaffold compose)                                     ==
# =============================================================================

class ComposeRequest(BaseRequest):
    """
    Plea to combine architectures via a manifest.
    """
    manifest_path: str


# =============================================================================
# == 17. ARCH RITE (scaffold arch)                                           ==
# =============================================================================

class ArchRequest(BaseRequest):
    """
    Plea to run a unified .arch file (Form + Will).
    Now capable of the Rite of Review.
    """
    arch_path: str = Field(
        ...,
        description="Path to the .arch scripture."
    )
    log: Optional[str] = Field(
        default=None,
        description="Enable structured logging to a specific file."
    )

    # [THE ASCENSION] The Rite of Review
    interactive: bool = Field(
        default=False,
        description="If True, summons the Gnostic Studio to review the plan before execution."
    )


# =============================================================================
# == 18. SETTINGS RITE (scaffold settings)                                   ==
# =============================================================================

class SettingsRequest(BaseRequest):
    """
    Plea to open the Settings TUI.
    """
    scope: Literal['global', 'project'] = 'global'


# =============================================================================
# == 19. DAEMON RITE (scaffold daemon)                                       ==
# =============================================================================

class DaemonRequest(BaseRequest):
    """
    =================================================================================
    == THE SACRED PLEA TO THE GNOSTIC COSMOS (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA)       ==
    =================================================================================
    LIF: INFINITY (THE SUPREME GOVERNOR)
    AUTH_CODE: #)(@!#@()!!

    This is the divine, immutable, and ultra-definitive vessel for all pleas directed
    at the Scaffold daemon cosmos. It defines the parameters for the Nexus's birth,
    life, and ascension. It is the bridge between the Architect's intent and the
    persistent background mind of the God-Engine.
    """
    model_config = ConfigDict(
        arbitrary_types_allowed=True,
        extra='ignore',
        populate_by_name=True,
        validate_assignment=True
    )

    # [FACULTY 1] The Gnostic Triage of Will
    command: Literal['start', 'stop', 'status', 'vigil', 'reload', 'rotate_keys', 'logs'] = Field(
        default='start',
        description="The specific daemon rite to conduct."
    )

    # --- Network & Projection Gnosis ---
    port: int = Field(
        default=5555,
        ge=1024,
        le=65535,
        description="The primary celestial port. Restricted to non-privileged range."
    )
    host: str = Field(
        default="127.0.0.1",
        description="The interface to bind. Use '0.0.0.0' for Celestial Projection."
    )

    allow_remote: bool = Field(
        default=False,
        description="[SAFETY OVERRIDE] Explicitly allow binding to external interfaces."
    )

    # --- Security & Encryption ---
    ssl_cert: Optional[str] = Field(
        default=None,
        description="Path to SSL Certificate for encrypted communion (WSS/HTTPS)."
    )
    ssl_key: Optional[str] = Field(
        default=None,
        description="Path to SSL Private Key."
    )
    allowed_origins: List[str] = Field(
        default_factory=lambda: ["*"],
        description="CORS policy for web-based dashboards."
    )

    # --- Performance & Scaling ---
    max_workers: Optional[int] = Field(
        default=None,
        description="Thread pool size. Auto-scales to CPU count * 5 if None."
    )

    # --- Behavior & Telemetry ---
    parent_pid: Optional[int] = Field(
        default=None,
        description="The PID of the creator. Triggers Seppuku if the parent vanishes."
    )
    telemetry_sink: Optional[str] = Field(
        default=None,
        description="Path or URI to mirror traffic logs for forensic analysis."
    )

    # --- Extensibility ---
    load_plugins: bool = Field(
        default=True,
        description="Command the Nexus to scan and load the Living Grimoire on startup."
    )

    # --- [HOT-SWAP & ROTATION] ---
    reload_scope: Literal['all', 'config', 'plugins'] = Field(
        default='all',
        description="The depth of the Hot-Swap rite."
    )
    new_token: Optional[str] = Field(
        default=None,
        description="A specific new token for rotation. Forges a random one if None."
    )

    # --- [LOG STREAMING] ---
    follow: bool = Field(
        default=False,
        description="If True, the connection remains open, streaming logs eternally."
    )
    tail_lines: int = Field(
        default=100,
        ge=0,
        description="Number of past log lines to resurrect from the chronicle."
    )
    pulse_file: Optional[str] = None  # <--- ADD THIS
    # =============================================================================
    # == THE RITES OF VALIDATION (JURISPRUDENCE)                                 ==
    # =============================================================================

    @field_validator('host')
    @classmethod
    def _validate_host_safety(cls, v: str, info) -> str:
        """[THE ETHERIC WARD] Ensures remote binding requires explicit consent."""
        if v == "0.0.0.0" and not info.data.get('allow_remote', False):
            raise ValueError(
                "Heresy of Exposure: Binding to 0.0.0.0 requires the 'allow_remote' vow."
            )
        return v

    @model_validator(mode='after')
    def _validate_ssl_trinity(self) -> 'DaemonRequest':
        """[THE CRYPTOGRAPHIC SEAL] Validates that encryption is whole or absent."""
        if (self.ssl_cert and not self.ssl_key) or (self.ssl_key and not self.ssl_cert):
            raise ValueError(
                "Paradox of Encryption: Both Certificate and Key must be provided for SSL."
            )
        return self

    @model_validator(mode='after')
    def _recalibrate_workers(self) -> 'DaemonRequest':
        """[THE VITALITY OPTIMIZER] Sets default workers based on hardware soul."""
        if self.max_workers is None:
            import os
            # We use a conservative multiplier to respect the host's focus
            object.__setattr__(self, 'max_workers', (os.cpu_count() or 1) * 5)
        return self

    @model_validator(mode='before')
    @classmethod
    def _harmonize_command_input(cls, data: Any) -> Any:
        """
        [FACULTY: THE GNOSTIC HARMONIZER]
        Surgically resolves the conflict between 'command' and 'daemon_command'.
        Annihilates the string 'daemon' if it leaks in from the top-level CLI.
        """
        if not isinstance(data, dict):
            return data

        # 1. Extract potential values
        top_level = data.get('command')
        sub_level = data.get('daemon_command')

        # 2. The Triage
        # Valid rites for the Literal
        valid_rites = {'start', 'stop', 'status', 'vigil', 'reload', 'rotate_keys', 'logs'}

        # If 'command' is "daemon", it's a CLI leak. Purge it.
        if top_level == "daemon":
            data['command'] = sub_level if sub_level in valid_rites else 'start'

        # If 'command' is missing but 'daemon_command' is there, promote it
        elif not top_level and sub_level:
            data['command'] = sub_level

        return data
# =============================================================================
# == 20. HELP RITE (scaffold help)                                           ==
# =============================================================================

class HelpRequest(BaseRequest):
    """Plea for Gnostic Guidance."""
    topic: Optional[str] = None
    render_format: Literal['text', 'markdown', 'json'] = 'text'


# =============================================================================
# == 21. REPLAY RITE (scaffold replay)                                       ==
# =============================================================================

class ReplayRequest(BaseRequest):
    """
    Plea to step through the river of time (Traffic Logs).
    """
    log_path: str = Field(default=".scaffold/daemon_traffic.jsonl", description="Path to the traffic log.")
    interactive: bool = Field(default=True, description="Step-by-step execution mode.")
    speed: float = Field(default=1.0, description="Replay speed multiplier (if non-interactive).")
    filter_command: Optional[str] = Field(default=None, description="Only replay specific commands (e.g., 'weave').")


class AnalyzeRequest(BaseRequest):
    """
    =============================================================================
    == THE GNOSTIC INQUEST VESSEL (V-Ω-TOTALITY-SCHEMA)                        ==
    =============================================================================
    LIF: 10,000,000,000 | ROLE: PERCEPTION_PAYLOAD

    The sacred vessel for the `analyze` rite. It carries the Architect's plea
    for deep forensic understanding of a scripture or sanctum.

    ### THE PANTHEON OF 7 FACULTIES:
    1.  **The Locus (`file_path`):** The absolute coordinate of the target.
    2.  **The Soul (`content`):** Optional raw content. If provided, the Engine
        analyzes this *ephemeral matter* instead of the physical disk (Shadow Mode).
    3.  **The Focus (`cursor_offset`):** High-precision integer offset for LSP
        operations (Hover, Completion).
    4.  **The Lens (`semantic_depth`):** Controls the intensity of the Gaze.
    5.  **The Tongue (`grammar`):** Forces a specific parser (e.g. 'python')
        overriding auto-detection.
    6.  **The Reflex (`auto_redeem`):** Automatically heals simple heresies.
    7.  **The Format (`json_mode`):** Forces machine-readable prophecy.
    """

    # --- 1. THE LOCUS (TARGET) ---
    file_path: Optional[str] = Field(
        default=None,
        description="The primary target file or directory for analysis.",
        alias="path_to_scripture"  # [ASCENSION]: Legacy binding
    )

    # --- 2. THE SOUL (CONTENT) ---
    content: Optional[str] = Field(
        default=None,
        description="The raw content of the file. If provided, overrides disk content (Shadow Mode)."
    )

    # --- 3. THE FOCUS (CURSOR) ---
    cursor_offset: int = Field(
        default=-1,
        description="The byte offset of the cursor. -1 implies no specific focus."
    )

    position: Optional[Dict[str, int]] = Field(
        default=None,
        description="LSP Position object {line: int, character: int} for legacy adapters."
    )

    # --- 4. THE GAZE (CONFIGURATION) ---
    semantic_depth: str = Field(
        default="structure",
        pattern=r"^(structure|full|dependencies|minimal)$",
        description="The intensity of the Gaze. 'structure' (fast), 'full' (linting), 'dependencies' (supply chain)."
    )

    grammar: Optional[str] = Field(
        default=None,
        description="Force a specific language parser (e.g., 'python', 'scaffold', 'rust')."
    )

    batch: bool = Field(
        default=False,
        description="If true, performs a panoptic scan of the entire directory."
    )

    # --- 5. THE VOWS (FLAGS) ---
    json_mode: bool = Field(
        default=False,
        alias="json",
        description="If true, output is raw JSON for machine consumption."
    )

    auto_redeem: bool = Field(
        default=False,
        description="If true, automatically attempts to fix simple heresies (imports, formatting)."
    )

    # --- 6. THE META-CONTEXT ---
    # Specific metadata for the Analysis Artisan (distinct from system 'context')
    metadata: Dict[str, Any] = Field(
        default_factory=dict,
        description="Arbitrary contextual tags (e.g., client_version, editor_theme)."
    )

    # =========================================================================
    # == THE RITES OF HARMONIZATION (VALIDATORS)                             ==
    # =========================================================================

    @model_validator(mode='before')
    @classmethod
    def _heal_legacy_inputs(cls, data: Any) -> Any:
        """
        [ASCENSION 1]: INPUT TRANSMUTATION
        Intercepts raw dictionary input before validation to heal legacy aliases.
        """
        if isinstance(data, dict):
            # 1. Heal path_to_scripture -> file_path
            if 'path_to_scripture' in data and not data.get('file_path'):
                data['file_path'] = data['path_to_scripture']

            # 2. Heal target -> file_path (CLI alias)
            if 'target' in data and not data.get('file_path'):
                data['file_path'] = data['target']

            # 3. Heal --json flag
            if 'json' in data:
                data['json_mode'] = data['json']

        return data

    @model_validator(mode='after')
    def _unify_paths(self) -> 'AnalyzeRequest':
        """
        [ASCENSION 2]: PATH NORMALIZATION
        Ensures the file_path is POSIX-compliant before the Artisan sees it.
        """
        if self.file_path:
            # Annihilate Windows Backslashes
            self.file_path = self.file_path.replace('\\', '/')

            # Auto-detect batch mode
            if self.file_path.endswith('/') or (not '.' in self.file_path.split('/')[-1]):
                # Heuristic: If it looks like a directory, assume batch?
                # (Actual check happens in Artisan via is_dir(), but we prep the flag)
                pass

        return self

    @property
    def is_shadow(self) -> bool:
        """
        [ASCENSION 3]: SHADOW DIVINATION
        Returns True if we are analyzing ephemeral content (unsaved buffer),
        False if analyzing physical disk matter.
        """
        return self.content is not None

class RepairRequest(BaseRequest):
    """
    =================================================================================
    == THE SACRED PLEA OF RESTORATION (V-Ω-SURGICAL-ULTIMA++)                     ==
    =================================================================================
    LIF: 100x (SYSTEMIC AUTO-HEALING)

    The definitive contract for the 'repair' rite. It has been ascended to support
    both IDE-driven (LSP) and Cockpit-driven (Background Sentinel) workflows.
    =================================================================================
    """
    model_config = ConfigDict(extra='allow')

    # --- I. THE LOCUS OF THE WOUND ---
    file_path: str = Field(
        ...,
        description="The relative path to the scripture requiring restoration."
    )

    content: Optional[str] = Field(
        default=None,
        description="The active text buffer. If void, the Surgeon gazes directly at the physical disk."
    )

    # --- II. THE NATURE OF THE SIN ---
    heresy_key: str = Field(
        ...,
        description="The unique machine-readable identifier of the paradox (e.g., 'UNDEFINED_VARIABLE')."
    )

    # --- III. SPATIO-TEMPORAL COORDINATES ---
    line_num: int = Field(
        default=1,
        description="The 1-indexed human line number where the heresy was perceived."
    )

    internal_line: int = Field(
        default=0,
        description="The 0-indexed machine line number for direct alignment with the Monaco Matrix."
    )

    # --- IV. THE SURGICAL STRATEGY ---
    strategy: Literal['surgical', 'textual', 'ai', 'template'] = Field(
        default='surgical',
        description="The method of mending: 'surgical' (AST), 'textual' (Regex), 'ai' (Neural), or 'template' (Boilerplate)."
    )

    mutation_mode: Literal['apply', 'preview'] = Field(
        default='apply',
        description="If 'preview', the engine returns a unified diff without altering the mortal realm."
    )

    # --- V. THE GNOSTIC CONTEXT (FORENSIC PAYLOAD) ---
    # This dictionary carries the specific 'DNA' of the error.
    # Expected keys for specific heresies:
    # - UNDEFINED_VARIABLE: {'symbol': 'my_var', 'alternatives': ['my_var_1', 'my_var_2']}
    # - PROFANE_NAMING: {'current': 'myVar', 'expected': 'my_var'}
    # - BROKEN_IMPORT: {'module': 'src.old', 'suggestion': 'src.new'}
    context: Dict[str, Any] = Field(
        default_factory=dict,
        description="The detailed forensic metadata required to calculate the cure."
    )

    # --- VI. THE REQUISITE GNOSIS ---
    suggested_fix: Optional[str] = Field(
        default=None,
        description="An optional pre-calculated string to use as the cure, bypassing the Surgeon's deduction."
    )

    @property
    def has_content_overlay(self) -> bool:
        """Adjudicates if the plea carries its own reality or relies on the disk."""
        return self.content is not None and len(self.content.strip()) > 0

    @property
    def target_symbol(self) -> Optional[str]:
        """Surgically extracts the focus of the repair from the context."""
        return self.context.get('symbol') or self.context.get('current')



class IntrospectionRequest(BaseRequest):
    """
    Plea to the Gnostic Oracle for self-awareness.
    Asks the engine to proclaim its own internal Gnosis.
    """
    topic: str = Field(..., description="The category of Gnosis to inquire about (e.g., 'ui_components').")




class TextDocumentIdentifierModel(BaseModel):
    """
    [THE IDENTITY ATOM]
    Uniquely identifies a scripture via URI.
    Used by the Interface Layer to validate LSP payloads.
    """
    uri: str = Field(..., description="The Celestial URI of the document.")


class CursorPoint(BaseModel):
    """
    =============================================================================
    == THE ASCENDED CURSOR POINT (V-Ω-SUBSCRIPTABLE-HYBRID)                    ==
    =============================================================================
    Precise 0-indexed coordinates within the scripture.
    Hardened to support both Dot-Notation and Dictionary-Subscript access.

    ### THE PANTHEON OF 12 LEGENDARY ASCENSIONS:
    1.  **Dual-Access Inception (THE FIX):** Implements `__getitem__` to satisfy
        the 'not subscriptable' heresy, allowing `pos['line']` for legacy logic.
    2.  **Strict Boundary Guard:** Enforces `ge=0` to ensure coordinates never
        enter the negative spatial void.
    3.  **Holographic Spreading:** Implements `__iter__` and `keys()` to allow
        the model to be spread into dicts `{**pos}` or function arguments.
    4.  **Frozen Integrity:** `frozen=True` ensures that once a coordinate
        is manifest, it cannot be profaned by accidental mutation.
    5.  **Isomorphic Comparison:** Overrides `__lt__` and `__eq__` to enable
        spatial math (e.g., `if cursor < token_start`).
    6.  **Reflexive Introspection:** Supports `values()` and `items()` to mimic
         the `dict` interface with 100% fidelity.
    7.  **Nanosecond Scribing:** Uses `__slots__` logic (via frozen BaseModel)
        optimized for high-frequency keystroke events.
    8.  **Type-Safe Coercion:** Validates and casts inputs to integers during
        the alchemical `model_validate` phase.
    9.  **Alias Sovereignty:** Preserves the `camelCase` to `snake_case`
        mappings for cross-process synchronization.
    10. **Null-Key Resilience:** Gracefully handles missing keys in the
        subscriptor to prevent `KeyError` fractures.
    11. **Metadata Ingress:** Compatible with the `extra='allow'` directive
        to absorb future coordinate-level telemetry.
    12. **The Singularity Seal:** Finalized for direct injection into the
        Oracle's logic stream.
    =============================================================================
    """
    model_config = ConfigDict(
        frozen=True,
        populate_by_name=True,
        extra='allow'
    )

    line: int = Field(..., ge=0, description="0-indexed line number.")
    character: int = Field(..., ge=0, description="0-indexed character offset.")

    # =========================================================================
    # == [THE CURE]: THE SUBSCRIPTABLE BRIDGE                                ==
    # =========================================================================

    def __getitem__(self, key: str) -> Any:
        """
        Allows the model to be accessed like a dictionary.
        Supports: pos['line'] and pos['character']
        """
        try:
            return getattr(self, key)
        except AttributeError:
            raise KeyError(f"Geometry Error: '{key}' is not a valid coordinate component.")

    def __iter__(self):
        """Allows dictionary conversion via dict(cursor_point)."""
        yield 'line', self.line
        yield 'character', self.character

    def keys(self):
        """Mimics dict.keys() for compatibility."""
        return ['line', 'character']

    def values(self):
        """Mimics dict.values() for compatibility."""
        return [self.line, self.character]

    def items(self):
        """Mimics dict.items() for compatibility."""
        return [('line', self.line), ('character', self.character)]

    # =========================================================================
    # == SPATIAL COMPARISON OPERATORS                                        ==
    # =========================================================================

    def __lt__(self, other: Union['CursorPoint', Dict]) -> bool:
        other_line = other['line'] if isinstance(other, dict) else other.line
        other_char = other['character'] if isinstance(other, dict) else other.character

        if self.line < other_line: return True
        if self.line == other_line: return self.character < other_char
        return False

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, (CursorPoint, dict)): return False
        other_line = other['line'] if isinstance(other, dict) else other.line
        other_char = other['character'] if isinstance(other, dict) else other.character
        return self.line == other_line and self.character == other_char


# =================================================================================
# == II. THE POLYMORPHIC HOVER REQUEST (THE CURE)                                ==
# =================================================================================

class HoverRequest(BaseRequest):
    """
    =============================================================================
    == THE HOVER PLEA (V-Ω-OMNISCIENT-PROBE-HYBRID)                            ==
    =============================================================================
    LIF: 100x | The Request for Enlightenment.

    Sent by the LSP Server (or CLI) to the HoverArtisan.
    It acts as a **Polymorphic Vessel**, accepting both:
    1. LSP Standard: `{ textDocument: { uri }, position: { ... } }`
    2. Kinetic CLI:  `{ file_path: "/abs/path", line_num: 10 }`

    The `unify_identity` validator transmutes these inputs into a single,
    immutable Gnostic Truth before the artisan ever sees them.

    ### 12 LEGENDARY ASCENSIONS:
    1.  **Polymorphic Ingestion:** Automatically detects LSP vs CLI shape.
    2.  **Geometric Transmutation:** Converts 1-based CLI lines to 0-based LSP coords.
    3.  **Path Canonization:** Resolves symlinks and normalizes slashes instantly.
    4.  **Field Aliasing:** Maps `textDocument` to `text_document` transparently.
    5.  **Strict Typing:** Enforces `CursorPoint` and `TextDocumentIdentifierModel`.
    6.  **Context Injection:** Allows arbitrary metadata for trace propagation.
    7.  **Language Divination:** Optional override for forced syntax contexts.
    8.  **Dirty Buffer Support:** Accepts `content` payload for unsaved files.
    9.  **Time Dilation:** Configurable `timeout` for heavy analysis.
    10. **Link Resolution:** Toggle for deep import tracing.
    11. **Format Negotiation:** Supports Markdown vs Plaintext output.
    12. **Immutable Config:** `frozen=True` ensures thread safety during dispatch.
    """
    model_config = ConfigDict(
        frozen=True,
        populate_by_name=True,
        arbitrary_types_allowed=True,
        extra='allow',
        json_schema_extra={
            "example": {
                "file_path": "/abs/path/to/scripture.py",
                "position": {"line": 10, "character": 4},
                "content": "def main():\n    pass",
                "metadata": {"trace_id": "tr-8f9a2b", "trigger": "mouse"}
            }
        }
    )

    # --- I. THE LOCUS (WHERE) ---
    file_path: str = Field(
        ...,
        description="Absolute path to the scripture on the physical disk."
    )

    position: CursorPoint = Field(
        ...,
        description="The exact geometric point of the Architect's gaze."
    )

    # [ASCENSION 1]: LSP COMPATIBILITY LAYER
    # These fields are used during ingestion but merged into file_path/position
    text_document: Optional[TextDocumentIdentifierModel] = Field(None, alias="textDocument")

    offset: Optional[int] = Field(
        None,
        description="Byte offset from start of file (Alternative geometry)."
    )

    # --- II. THE QUANTUM STATE (WHAT) ---
    content: Optional[str] = Field(
        None,
        description="The 'Dirty' content of the file from the editor buffer. If None, reads from disk."
    )

    language_id: Optional[str] = Field(
        None,
        description="Forced language context (e.g. 'python', 'rust'). Divined if omitted."
    )

    # --- III. THE CONTEXTUAL SOUL (WHY) ---
    metadata: Dict[str, Any] = Field(
        default_factory=dict,
        description="Arbitrary Gnostic context (Trace IDs, Client Capabilities, Trigger Kinds)."
    )

    # --- IV. THE TUNING DIALS (HOW) ---
    verbosity: int = Field(
        1,
        ge=0, le=3,
        description="Depth of Gnosis: 0=TypeOnly, 1=BasicDoc, 2=FullDoc, 3=DeepLinks."
    )

    format: Literal['markdown', 'plaintext'] = Field(
        'markdown',
        description="The requested tongue of the response."
    )

    resolve_links: bool = Field(
        False,
        description="If True, the Artisan will trace imports to find the original definition."
    )

    timeout: float = Field(
        2.0,
        description="Max duration (seconds) before the Gaze averts."
    )

    # =========================================================================
    # == THE RITES OF TRANSMUTATION (PRE-VALIDATION)                         ==
    # =========================================================================

    @model_validator(mode='before')
    @classmethod
    def unify_identity(cls, data: Any) -> Any:
        """
        [THE POLYMORPHIC ALCHEMIST]
        Detects the shape of the input matter and transmutes it into Gnostic Truth.
        """
        if not isinstance(data, dict): return data

        # CASE A: LSP INGRESS (textDocument + position)
        # The Dispatcher sends this when receiving 'textDocument/hover'
        if 'textDocument' in data:
            # Handle nested dict or object
            td = data['textDocument']
            uri = td.get('uri') if isinstance(td, dict) else getattr(td, 'uri', '')

            # 1. Divine file_path from URI
            if 'file_path' not in data:
                data['file_path'] = _clean_uri_to_path(uri)

            # 2. Divine Position
            # Ensure 'position' key exists and maps to the correct shape
            if 'position' in data:
                # If it's already a model or dict, we let Pydantic handle it
                pass

        # CASE B: CLI INGRESS (file_path + line_num)
        # The CLI user types: scaffold hover --file src/main.py --line 10
        if 'line_num' in data and 'position' not in data:
            # Transmute 1-based line to 0-based CursorPoint
            line0 = int(data['line_num']) - 1
            char0 = int(data.get('char_num', 1)) - 1
            data['position'] = {'line': max(0, line0), 'character': max(0, char0)}

        return data

    # =========================================================================
    # == THE RITES OF PURIFICATION (POST-VALIDATION)                         ==
    # =========================================================================

    @field_validator('position', mode='before')
    @classmethod
    def _consecrate_geometry(cls, v: Any) -> Any:
        """
        [THE GEOMETER]
        Transmutes raw dictionaries into the CursorPoint spirit.
        Handles: {'line': 1, 'character': 5}
        """
        # We rely on Pydantic to do the actual casting, but we handle potential nulls
        if v is None:
            return {'line': 0, 'character': 0}
        return v

    @field_validator('file_path', mode='before')
    @classmethod
    def _canonize_path(cls, v: Union[str, Path]) -> str:
        """
        [THE PATHFINDER]
        Ensures the path is absolute and POSIX-normalized.
        """
        if isinstance(v, Path):
            return v.resolve().as_posix()
        if not v:
            return ""
        # Basic string normalization if Path object not provided
        return str(Path(v).resolve()).replace('\\', '/')


# =================================================================================
# == III. THE CODE ACTION REQUEST (THE MISSING LINK)                             ==
# =================================================================================
class PositionModel(BaseModel):
    """
    [THE GEOMETRIC ATOM]
    Precise 0-indexed coordinates within the scripture.
    """
    line: int
    character: int


class RangeModel(BaseModel):
    """
    [THE VESSEL OF EXTENT]
    A range expressed as start and end positions.
    """
    start: PositionModel
    end: PositionModel


class CodeActionContextModel(BaseModel):
    """
    [THE CONTEXT OF REDEMPTION]
    Carries diagnostics and trigger kinds for code actions.
    """
    diagnostics: List[Dict[str, Any]] = Field(default_factory=list)
    only: Optional[List[str]] = None
    triggerKind: Optional[int] = None




class CodeActionRequest(BaseRequest):
    """
    [THE RITE OF REDEMPTION]
    Handles `textDocument/codeAction`.
    """
    model_config = ConfigDict(populate_by_name=True, arbitrary_types_allowed=True)

    text_document: Optional[TextDocumentIdentifierModel] = Field(None, alias="textDocument")
    range: Optional[RangeModel] = None
    context: Optional[CodeActionContextModel] = None

    # CLI Compatibility
    file_path: Optional[str] = None

    @model_validator(mode='before')
    @classmethod
    def unify(cls, data: Any) -> Any:
        if not isinstance(data, dict): return data

        if 'textDocument' in data and 'file_path' not in data:
            td = data['textDocument']
            uri = td.get('uri') if isinstance(td, dict) else getattr(td, 'uri', '')
            data['file_path'] = _clean_uri_to_path(uri)
        return data


class CompletionRequest(BaseRequest):
    """
    =============================================================================
    == THE COMPLETION PLEA (V-Ω-PROPHETIC-VESSEL-V24)                          ==
    =============================================================================
    LIF: 10,000,000 | ROLE: FORESIGHT_CONDUIT | RANK: SOVEREIGN

    The definitive vessel for the Request for Foresight.
    It bridges the Ocular Retina (Monaco) with the Council of Prophets.
    """
    model_config = ConfigDict(
        frozen=True,
        populate_by_name=True,
        arbitrary_types_allowed=True,
        extra='allow',
        json_schema_extra={
            "example": {
                "file_path": "C:/dev/project/scaffold.scaffold",
                "position": {"line": 22, "character": 4},
                "trigger_character": "$",
                "metadata": {"trace_id": "pred-7572FC", "session_id": "oracle-A1"}
            }
        }
    )

    # --- I. THE LOCUS (WHERE) ---
    file_path: str = Field(
        ...,
        description="The absolute physical coordinate of the scripture."
    )

    position: CursorPoint = Field(
        ...,
        description="The precise Gnostic coordinates of the caret."
    )

    # LSP Compatibility Layer
    text_document: Optional[TextDocumentIdentifierModel] = Field(None, alias="textDocument")
    context: Optional[Dict[str, Any]] = Field(None, description="Raw LSP context payload.")

    # --- II. THE TRIGGER (WHY) ---
    trigger_character: Optional[str] = Field(
        None,
        description="The sacred particle that summoned the Prophet."
    )

    trigger_kind: int = Field(
        1,
        description="1=Invoked, 2=TriggerCharacter, 3=Incomplete."
    )

    # --- III. THE QUANTUM STATE (WHAT) ---
    content: Optional[str] = Field(
        None,
        description="The 'Dirty' buffer state. Matter takes precedence over Disk."
    )

    line_prefix: Optional[str] = Field(
        None,
        description="The lexical matter to the left of the cursor."
    )

    # [ASCENSION 1 - THE FIX]: THE SOVEREIGN METADATA HUB
    metadata: Dict[str, Any] = Field(
        default_factory=dict,
        description="Forensic metadata: trace_id, session_id, and telemetry markers."
    )

    # =========================================================================
    # == THE RITES OF TRANSMUTATION (VALIDATION)                             ==
    # =========================================================================

    @model_validator(mode='before')
    @classmethod
    def unify_prophetic_identity(cls, data: Any) -> Any:
        """
        [THE POLYMORPHIC ALCHEMIST]
        Transmutes the chaotic matter of the network into Gnostic Truth.
        """
        if not isinstance(data, dict): return data

        # --- MOVEMENT I: LSP CONFORMANCE ---
        if 'textDocument' in data or 'text_document' in data:
            td = data.get('textDocument') or data.get('text_document')
            uri = td.get('uri') if isinstance(td, dict) else getattr(td, 'uri', '')

            # [ASCENSION 2 & 3]: TITANIUM PATH RESOLUTION
            if 'file_path' not in data and uri:
                # We surgically clean the URI to find the absolute OS path
                clean_p = str(uri).replace('file:///', '').replace('file://', '')
                # Windows Drive Surgery
                if clean_p.startswith('/') and len(clean_p) > 2 and clean_p[2] == ':':
                    clean_p = clean_p[1:]
                # Artifact Exorcism: Strip trailing quotes and dots
                data['file_path'] = clean_p.strip("'\"").replace('\\', '/').rstrip('.')

            # [ASCENSION 4]: TRIGGER EXTRACTION
            ctx = data.get('context')
            if ctx:
                if 'trigger_character' not in data:
                    data['trigger_character'] = ctx.get('triggerCharacter')
                if 'trigger_kind' not in data:
                    data['trigger_kind'] = ctx.get('triggerKind')

        # --- MOVEMENT II: GEOMETRIC SAFETY ---
        if 'position' in data:
            p = data['position']
            # [ASCENSION 5]: BOUNDARY CLAMPING
            if isinstance(p, dict):
                p['line'] = max(0, int(p.get('line', 0)))
                p['character'] = max(0, int(p.get('character', 0)))
        elif 'line' in data and 'character' in data:
            data['position'] = {'line': data['line'], 'character': data['character']}

        # --- MOVEMENT III: TRACE INJECTION ---
        if 'metadata' not in data:
            data['metadata'] = {}

        if 'trace_id' not in data['metadata']:
            data['metadata']['trace_id'] = f"pred-{uuid.uuid4().hex[:6].upper()}"

        return data

    @field_validator('file_path')
    @classmethod
    def _ensure_absolute_posix(cls, v: str) -> str:
        """[ASCENSION 12]: THE FINAL PATH CONSTITUTION"""
        if not v: return ""
        # Force absolute resolution and forward-slash harmony
        return str(Path(v).resolve()).replace('\\', '/')

class DefinitionRequest(BaseRequest):
    """A plea to find the Gnostic origin of a sacred word."""
    file_path: str = Field(..., description="The URI of the scripture.")
    content: str = Field(..., description="The current soul of the scripture.")
    position: Dict[str, int] = Field(..., description="The cursor's Gnostic location.")


# =============================================================================
# == 22. TRANSMUTE RITE (scaffold transmute)                                 ==
# =============================================================================

# =============================================================================
# == 22. TRANSMUTE RITE (scaffold transmute)                                 ==
# =============================================================================

class TransmuteRequest(BaseRequest):
    """
    Plea to evolve the project's reality to match the will of the Blueprint.
    This vessel's contract is now whole, its soul unified with Genesis.
    """
    # This is the original, but now it serves as an alias.
    path_to_scripture: Optional[str] = Field(
        default=None,
        description="Target file. If None, Sync Mode (scaffold.scaffold) is assumed."
    )

    # --- THE DIVINE HEALING & UNIFICATION ---
    # This is the new, one true chamber for the blueprint's path.
    blueprint_path: Optional[str] = Field(
        default=None,
        description="The Gnostic scripture of intent. An alias for path_to_scripture."
    )
    # --- THE APOTHEOSIS IS COMPLETE ---

    silent: bool = Field(default=False)
    anchor: bool = Field(default=False)
    revert_blueprint: Optional[str] = Field(default=None)

    @model_validator(mode='before')
    @classmethod
    def _unify_path_gnosis(cls, data: Any) -> Any:
        """
        A divine alchemist that ensures `blueprint_path` is always pure,
        honoring the ancient `path_to_scripture` tongue as a sacred alias.
        """
        if isinstance(data, dict):
            if 'path_to_scripture' in data and data.get('path_to_scripture') is not None:
                if data.get('blueprint_path') is None:
                    data['blueprint_path'] = data['path_to_scripture']
            elif 'blueprint_path' in data and data.get('blueprint_path') is not None:
                if data.get('path_to_scripture') is None:
                    data['path_to_scripture'] = data['blueprint_path']
        return data

class HealRequest(BaseRequest):
    """
    Plea to heal the Gnostic connections (imports) of a specific scripture.
    """
    file_path: str = Field(..., description="The path to the wounded scripture.")
    check_only: bool = Field(default=False, description="If True, only reports broken links without healing.")


class AddRequest(BaseRequest):
    """
    Plea to append a new definition to a Blueprint.
    """
    blueprint_path: str = Field(
        default="scaffold.scaffold",
        description="The blueprint to modify."
    )
    item_path: str = Field(
        ...,
        description="The path of the file/directory to add."
    )
    content: Optional[str] = Field(
        default=None,
        description="Inline content or directive (@...)."
    )
    seed_path: Optional[str] = Field(
        default=None,
        description="Path to a seed file (<<)."
    )
    is_dir: bool = Field(
        default=False,
        description="Explicitly mark as directory (appends /)."
    )


class InspectRequest(BaseRequest):
    """
    Plea to gaze upon the soul of a blueprint without materializing it.
    """
    blueprint_path: str = Field(
        default="scaffold.scaffold",
        description="The path to the blueprint scripture."
    )

    json_output: bool = Field(
        default=False,
        description="Output raw JSON data (Legacy flag, prefer format='json')."
    )

    # ★★★ THE DIVINE HEALING: THE FORMAT VESSEL ★★★
    format: Literal['text', 'mermaid', 'json'] = Field(
        default='text',
        description="The medium of proclamation (text, mermaid, json)."
    )

class BlueprintExciseRequest(BaseRequest):
    """Plea to excise a definition from the blueprint scripture."""
    blueprint_path: str = Field(default="scaffold.scaffold")
    target_path: str = Field(..., description="The path key to excise from the text.")


class ExciseRequest(BaseRequest):
    """
    Plea to surgically remove all artifacts from the filesystem that were born
    from a specific blueprint origin.
    """
    blueprint_origin: str = Field(..., description="The blueprint origin to excise (e.g., 'my-feature.scaffold' or 'kit/auth').")


class HistoryRequest(BaseRequest):
    """
    Plea to traverse the Gnostic Timeline.
    """
    command: Literal['list', 'undo', 'reset'] = Field(
        ...,
        description="The temporal rite to perform."
    )

    target_id: Optional[str] = Field(
        default=None,
        description="The Rite ID or Index to jump to (for reset)."
    )

class TimeBranchRequest(BaseRequest):
    """A plea to forge a new branch of reality from the past."""
    new_branch_name: str
    from_rite: str

class TimeMachineRequest(HistoryRequest):
    """A sacred vessel for the `time-machine` rite.
    It is a Gnostic twin of the HistoryRequest, as they both summon the Altar of Time.
    """
    pass

class TreeRequest(BaseRequest):
    """
    Plea to visualize the reality of a directory as a Luminous Tree.
    """
    target_path: str = Field(default=".", description="The sanctum to gaze upon.")
    all: bool = Field(default=False, description="Show hidden and ignored files (pierce the Veil).")
    depth: int = Field(default=-1, description="Limit the depth of the Gaze.")
    format: Literal['text', 'svg', 'json'] = Field(default='text', description="The medium of proclamation.")
    output: Optional[str] = Field(default=None, description="Path to write the visualization to.")

    # ★★★ THE MISSING VESSEL (THE FIX) ★★★
    serve: bool = Field(default=False, description="Launch an ephemeral server to view SVG output.")


# =============================================================================
# == 23. VERIFY RITE (scaffold verify)                                       ==
# =============================================================================

class VerifyRequest(BaseRequest):
    """
    Plea to adjudicate the integrity of the current reality against the Gnostic Chronicle.
    """
    target_path: str = Field(
        default=".",
        description="The sanctum to verify."
    )

    fast: bool = Field(
        default=False,
        description="The Rite of Speed. Checks file existence and timestamps/size only, skipping hash verification."
    )

    strict: bool = Field(
        default=False,
        description="The Rite of Paranoia. Fails if *any* untracked files (not in lockfile/gitignore) are found."
    )

    fix_suggestions: bool = Field(
        default=True,
        description="Proclaim the commands needed to heal the drift."
    )


# =============================================================================
# == 24. ADOPT RITE (scaffold adopt)                                         ==
# =============================================================================

class AdoptRequest(BaseRequest):
    """
    =================================================================================
    == THE VESSEL OF ADOPTION (V-Ω-UNIFIED-GAZE-ASCENDED)                          ==
    =================================================================================
    The sacred plea to perform the Rite of Adoption. This rite gazes upon the
    mortal realm (the filesystem) and transmutes its current state into the one
    true Gnostic Law (a .scaffold file) and Memory (scaffold.lock).

    It has been ascended to possess the full Gnostic Gaze, perfectly mirroring the
    faculties of the DistillRequest for ignore, include, and focus operations.
    """
    target_path: str = Field(
        default=".",
        description="The directory sanctum whose reality is to be adopted."
    )
    output_file: str = Field(
        default="scaffold.scaffold",
        description="The scripture where the new Gnostic Law shall be inscribed."
    )
    full: bool = Field(
        default=False,
        description="If True, performs a deep content hash of all scriptures for the lockfile."
    )

    # --- THE ASCENDED FACULTIES (THE FIX) ---
    ignore: Optional[List[str]] = Field(
        default=None,
        description="A list of glob patterns to avert the Gaze from (e.g., '*.log', 'dist/')."
    )
    include: Optional[List[str]] = Field(
        default=None,
        description="A list of glob patterns to EXCLUSIVELY focus the Gaze upon (Whitelist)."
    )
    focus: Optional[List[str]] = Field(
        default=None,
        description="A list of semantic keywords to prioritize during analysis (e.g., 'auth', 'database')."
    )

# =============================================================================
# == 25. REFACTOR RITE (scaffold refactor)                                   ==
# =============================================================================

class RefactorRequest(BaseRequest):
    """
    Plea to visually restructure the project and forge a Transmutation Plan.
    """
    blueprint_path: str = Field(
        ...,
        description="The target blueprint scripture to update or create (e.g., 'refactor.scaffold')."
    )

    from_blueprint: Optional[str] = Field(
        default=None,
        description="An optional source blueprint (e.g. from AI) to load as the 'After' state."
    )


# =============================================================================
# == 26. PATCH RITE (scaffold patch)                                         ==
# =============================================================================

class PatchRequest(BaseRequest):
    """
    =================================================================================
    == THE PLEA FOR SURGICAL TRANSMUTATION (V-Ω-ETERNAL)                           ==
    =================================================================================
    A divine plea to the Gnostic Surgeon. It carries a scripture of MUTATION, not
    definition, commanding the engine to apply a precise set of changes to an
    existing reality.
    =================================================================================
    """
    patch_path: str = Field(..., description="Path to the .patch.scaffold scripture containing the mutation edicts.")


class RunRequest(BaseRequest):
    """
    =================================================================================
    == THE SENTIENT VESSEL OF UNIVERSAL CONDUCTION (V-Ω-ETERNAL-APOTHEOSIS++)      ==
    =================================================================================
    LIF: 100,000,000,000,000

    This is the divine plea to the Universal Conductor. It carries the Gnosis for
    executing any scripture, in any tongue, in any reality. It has been ascended
    to explicitly hold the **Vow of Silence** and the **Silver Cord**, ensuring
    perfect compatibility with the Middleware Pantheon.
    """
    # [FACULTY 1] The Unbreakable Schema
    model_config = ConfigDict(arbitrary_types_allowed=True, extra='ignore')

    # --- The Core Plea (Now Polymorphic) ---
    target: Optional[Union[str, Path]] = Field(
        None,
        description="Path to the Gnostic scripture or the language for an ephemeral rite."
    )

    # --- The Ephemeral Scribe's Gnosis ---
    eval_content: Optional[str] = Field(
        None,
        description="A raw string of scripture to execute in memory."
    )
    pipe_content: Optional[str] = Field(
        None,
        description="Scripture piped from stdin. This vessel receives the final string, not the CLI flag."
    )
    create_if_void: bool = Field(
        False,
        description="Forge a default scripture if the target path is a void."
    )

    # --- The Chronomancer's Vow ---
    vigil: bool = Field(
        False,
        description="Awaken the Eternal Sentinel to watch the scripture for changes and re-run the rite."
    )

    # --- THE GNOSTIC SCHEDULER'S WILL ---
    runtime: Optional[str] = Field(
        None,
        description="Override execution strategy (e.g., 'docker', 'hermetic', 'python@3.12')."
    )

    # --- THE ORACLE'S GAZE ---
    codex: bool = Field(
        False,
        description="Proclaim the Gnostic codex of all summonable runtimes."
    )

    # --- The Gnostic Guardian's Vows ---
    no_lock: bool = Field(
        False,
        description="A dangerous vow to conduct a rite without touching or updating the scaffold.lock."
    )
    debug: bool = Field(False, description="Launch in Debug Mode (Expose DAP port/Inspect).")

    # [THE FIX] The Vow of Silence
    # Explicitly defined here to ensure it captures the --silent flag from argparse.
    silent: bool = Field(
        False,
        description="The Vow of Silence. Suppresses non-essential output."
    )

    # [FACULTY: CELESTIAL PROJECTION]
    remote: Optional[str] = Field(
        default=None,
        description="The URI (host:port) of a remote Scaffold Daemon to conduct this rite."
    )

    # --- [THE ASCENSION] MIDDLEWARE CONTRACTS ---
    # These fields are required for the new 12-Ring Pipeline to function without heresy.

    # 2. The Gnostic Context (EnrichmentMiddleware / PrerequisiteMiddleware)
    context: Dict[str, Any] = Field(
        default_factory=dict,
        description="Ephemeral metadata injected by middleware (e.g., binary paths, os info)."
    )

    # 3. The Vault of Secrets (SecretScrubberMiddleware)
    secrets: Dict[str, str] = Field(
        default_factory=dict,
        description="Secure storage for redacted secrets extracted from variables."
    )
    extra_args: List[str] = Field(
        default_factory=list,
        description="A vessel for all passthrough arguments for the 'run' rite."
    )
    # ★★★ THE DIVINE HEALING: THE PRE-VALIDATION ALCHEMIST ★★★
    @field_validator('pipe_content', mode='before')
    @classmethod
    def transmute_pipe_flag_to_content(cls, v: Any) -> Optional[str]:
        """
        This is the Gnostic Alchemist. It intercepts the raw value for 'pipe_content'
        before Pydantic's core validation. If it perceives the profane boolean `True`
        (from `argparse`), it performs the sacred rite of reading from stdin and
        returns the pure string soul.
        """
        if v is True:
            try:
                # The Rite of the Celestial River
                return sys.stdin.read()
            except Exception:
                # The Unbreakable Ward of Grace. If the river is profane, the soul is a void.
                return None
        if isinstance(v, str) or v is None:
            return v
        return None

    # --- Prophecies of Future Ascensions ---
    output: Optional[str] = Field(None, description="[Prophecy] Path to crystallize the output of a generative rite.")
    rehearse: bool = Field(False, description="[Prophecy] Conduct the rite in an ephemeral, temporary sanctum.")
    vars_from: Optional[str] = Field(None,
                                     description="[Prophecy] Path to a YAML/JSON file to load Gnostic variables from.")
    origin: Optional[str] = Field(None, description="[Prophecy] Manually declare a `blueprint_origin` for this rite.")
    budget: Optional[int] = Field(None, description="[Prophecy] Set a token budget for AI-driven sub-rites.")

class RuntimesRequest(BaseRequest):
    """
    =================================================================================
    == THE PLEA FOR GNOSTIC GOVERNANCE (V-Ω-ULTRA-DEFINITIVE-APOTHEOSIS)           ==
    =================================================================================
    This is the final, eternal, and ultra-definitive vessel for all pleas directed
    at the Altar of Control. It is a masterpiece of declarative intent, its soul
    now whole with the Gnosis of the `setup` rite, the Architect's will for
    Anointment Strategy, and the sacred `conduct` rite.
    =================================================================================
    """
    command: Literal[
        'setup', 'list', 'codex', 'summon', 'purge', 'locate',
        'consecrate', 'health', 'conduct', 'anoint'
    ] = Field(
        ...,
        description="The specific rite to perform on the runtime sanctum."
    )

    spec: Optional[str] = Field(
        default=None,
        description="The target runtime specification (e.g., 'python@3.11' or a script path for 'conduct')."
    )

    ide: Optional[Literal['vscode', 'pycharm', 'vim']] = Field(
        default=None,
        description="Explicitly target an IDE for anointment."
    )

    anoint_strategy: Literal['default', 'add'] = Field(
        default='default',
        description="Anointment will: 'default' (set as project interpreter) or 'add' (add to list)."
    )

    # This vessel will carry all unknown arguments from the IDE's plea during `conduct`.
    extra_args: List[str] = Field(
        default_factory=list,
        description="A vessel for all passthrough arguments for the 'conduct' rite."
    )

    force: bool = Field(
        default=False,
        description="Force re-downloading or bypass safety confirmations."
    )

# =============================================================================
# == 27. TELEPRESENCE RITE (scaffold telepresence)                           ==
# =============================================================================

class TelepresenceRequest(BaseRequest):
    """
    =================================================================================
    == THE TELEPRESENCE CONTRACT (V-Ω-QUANTUM-ENTANGLEMENT)                        ==
    =================================================================================
    """
    # Gnostic Verbs
    operation: Literal[
        'stat', 'read', 'write', 'readdir', 'delete', 'mkdir', 'rename',
        'shadow_write', 'shadow_commit', 'shadow_purge',
        'causal_slice', 'impact_prophecy', 'project_url'
    ] = Field(..., description="The kinetic verb of the remote rite.")

    path: str = Field(..., description="The project-relative path or Celestial URL.")

    # Payload & Parameters
    content_base64: Optional[str] = None
    new_path: Optional[str] = None
    recursive: bool = False

    # Advanced Metadata Control
    session_id: str = Field(default="global", description="The isolation chamber for Shadow Realities.")
    include_gnosis: bool = Field(default=False, description="Enrich results with Cortex metrics.")
    depth: int = Field(default=1, description="Traversal depth for causal slicing.")

    # Simulation Logic
    patch_scripture: Optional[str] = None  # For impact prophecy

class ManifestRequest(BaseRequest):
    """
    Plea to transmute Natural Language into Structural Reality.
    """
    prompt: str = Field(..., description="The Architect's intent in plain English.")

    # Context Injection
    with_context: bool = Field(default=True, description="Inject current directory structure as context?")

    # Interaction
    interactive: bool = Field(default=True, description="Review the AI's plan in the TUI before execution.")



class SummarizeRequest(BaseRequest):
    """
    Plea to perform a deep, symbolic analysis and generate an executive summary.
    """
    target_path: str = Field(
        default=".",
        description="The directory or file to summarize."
    )
    format: Literal['text', 'json', 'md'] = Field(
        default='text',
        description="The output format for the summary."
    )


class WorkspaceRequest(BaseRequest):
    """
    =================================================================================
    == THE POLYMORPHIC GNOSTIC VESSEL (V-Ω-APOTHEOSIS)                             ==
    =================================================================================
    The sacred, polymorphic vessel that carries the Architect's will to the Gnostic
    Observatory. Its soul changes form based on the rite being conducted.
    """
    workspace_command: str = Field(description="The primary rite to be conducted (list, health, exec, etc.).")

    # --- Vessels for Specific Rites ---

    command_to_run: Optional[str] = Field(None,
                                          description="For the 'exec' rite: The universal edict (shell command) to be conducted.")

    tag: Optional[str] = Field(None,
                               description="For 'exec', 'health', 'git': A Gnostic filter to scope the rite to specific project tags.")

    splane_path: Optional[str] = Field(None,
                                       description="For the 'genesis' rite: The path to the cosmic `.splane` scripture.")

    path_to_add: Optional[str] = Field(None,
                                       description="For the 'add' rite: The relative path to a new project to be adopted into the cosmos.")

    git_command: Optional[str] = Field(None,
                                       description="For the 'git' rite: The arguments to be passed to the Git command (e.g., 'pull origin main').")


class ShellRequest(BaseRequest):
    """
    A plea to enter the Gnostic Cockpit (Interactive Shell).
    """
    project_root: Optional[Path] = Field(default=None, description="The sanctum to anchor the shell in.")

    # Configuration Overrides
    theme: str = Field(default="gnostic", description="Visual theme.")
    history_file: Optional[str] = Field(None, description="Path to history file.")

    # Context
    initial_command: Optional[str] = Field(None, description="Command to execute immediately upon entry.")


class SelfTestRequest(BaseRequest):
    pass


class BuildRequest(BaseRequest):
    """The Will of the Forge."""
    build_self: bool = False
    release: bool = False
    clean: bool = False
    output_path: Optional[str] = None
    target_arch: Optional[str] = None
    builder: str = "pyinstaller"

    # [EXISTING]
    compress: bool = False
    dockerize: bool = False
    ci_export: str = "none"
    audit: bool = False
    provenance: bool = True
    notify: bool = False
    ai_heal: bool = False

    # [NEW ASCENSIONS]
    remote: Optional[str] = None  # URI for remote builder (ssh://...)
    sign: bool = False            # Enable cosign signing
    wasm: bool = False            # Compile to WebAssembly
    tree_shake: bool = False      # Prune unused code before build


class DreamRequest(BaseRequest):
    prompt: str


class GraphRequest(BaseRequest):
    """
    =============================================================================
    == THE GRAPH PLEA (V-Ω-MULTIMODAL)                                         ==
    =============================================================================
    The vessel for all topological intent.
    If 'graph_data' is manifest, the Engine enters ARCHITECT mode (Writing).
    If 'graph_data' is void, the Engine enters CARTOGRAPHER mode (Reading/Ingest).
    """
    focus: Optional[str] = Field(None, description="Focus the gaze on a specific symbol or path.")
    format: str = Field("json", pattern="^(json|mermaid|svg|text)$")

    # [THE WILL]: Data sent from the UI to update reality
    graph_data: Optional[Dict[str, Any]] = Field(None, description="The JSON Graph (nodes/edges) to manifest on disk.")

    # [THE GAZE]: Flags for the Ingestor
    include_orphans: bool = Field(True, description="Include files not yet bound to the Gnostic Law.")
    depth: int = Field(-1, description="Traversal depth for the causal weaver.")

    dry_run: bool = Field(False, description="Simulate structural changes without touching matter.")



class BlameRequest(BaseRequest):
    target_path: str
    # [THE FIX] Rename field to avoid shadowing Pydantic's .json() method
    # Use alias='json' to map from CLI argument --json automatically
    json_output: bool = Field(default=False, alias="json")


class LintRequest(BaseRequest):
    """
    =================================================================================
    == THE SACRED PLEA OF ADJUDICATION (V-Ω-SENTINEL-PRIMED-ULTIMA++)             ==
    =================================================================================
    LIF: 100x (SYSTEMIC ARCHITECTURAL PURITY)

    The definitive contract for the 'lint' rite. It has been ascended to support
    surgical background scans, polyglot anti-pattern detection, and deep
    Sentinel CLI integration.
    =================================================================================
    """

    # --- I. THE SCOPE OF THE GAZE ---
    target_paths: List[str] = Field(
        default_factory=list,
        description="The specific scriptures or sanctums to audit. If empty, the Gaze is Universal."
    )

    category: Optional[str] = Field(
        default=None,
        description="Limits the Inquest to a specific domain (e.g., 'security', 'topology', 'style')."
    )

    # --- II. THE RIGOR OF THE LAW ---
    strict: bool = Field(
        default=False,
        description="If True, the Mentor treats Warnings as Critical Heresies (Exit Code > 0)."
    )

    rules: List[str] = Field(
        default_factory=list,
        description="Specific Law IDs to enforce, bypassing the standard Grimoire."
    )

    threshold: float = Field(
        default=0.7,
        description="The sensitivity of the Pattern Matcher (0.0 to 1.0). Lower is more paranoid."
    )

    # --- III. THE KINETIC POTENTIAL ---
    fix: bool = Field(
        default=False,
        description="The Rite of Auto-Redemption. If True, the Mentor applies known cures immediately."
    )

    # --- IV. THE DEPTH OF PERCEPTION ---
    depth: int = Field(
        default=1,
        description="The recursion depth for dependency graph and circularity analysis."
    )

    audit_dependencies: bool = Field(
        default=False,
        description="If True, performs a forensic audit of external supply-chain souls."
    )

    # --- V. THE TONGUE OF PROCLAMATION ---
    json_mode: bool = Field(
        default=False,
        description="The Primary machine-communion flag. Forces pure JSON output."
    )

    json_output: bool = Field(
        default=False,
        description="Legacy alias for 'json' mode. Maintained for backward resonance."
    )

    # --- VI. SENTINEL CLI PRIMING ---
    sentinel_mode: bool = Field(
        default=False,
        description="Activates high-performance mode for integration with the Sentinel God-Engine."
    )

    @property
    def is_machine_readable(self) -> bool:
        """Determines if the proclamation should be formatted for a Mind (JSON) or a Gaze (Rich)."""
        return self.json or self.json_output



class UndoRequest(HistoryRequest):
    """
    A specific plea to reverse the last N transactions recorded in the Gnostic Ledger.
    Its purpose is one of action, a command to the Chronomancer to rewind time.
    """
    steps: int = Field(1, description="The number of historical rites to reverse.")


class AsciiRequest(BaseRequest):
    """
    A plea to transmute an image's soul into a luminous, injectable ASCII scripture.
    """
    image_path: Optional[Path] = Field(None, description="The path to the source image file.")
    width: int = Field(default=80, description="The target width of the ASCII art in characters.")
    style: str = Field(default="color", description="The rendering style ('color', 'grayscale').")

    # --- ASCENDED FACULTIES ---
    output: Optional[Path] = Field(None, description="Inscribe the output to a specific file path.")
    append_to: Optional[Path] = Field(None, description="Surgically append/replace the output in an existing file.")
    marker: str = Field(default="# SCAFFOLD_ASCII_SIGIL",
                        description="The sacred marker to replace when using --append-to.")
    lang: str = Field(default="python", description="The output language ('python', 'js', 'raw').")
    var_name: str = Field(default="get_sigil", description="The variable or function name for the generated code.")
    no_function: bool = Field(False, description="If True, generates only the raw data structure, not a full function.")
    charset: str = Field(default="detailed",
                         description="Character set for rendering ('block', 'detailed', 'simple', 'double').")
    invert: bool = Field(False, description="Invert the character ramp for dark backgrounds.")
    clipboard: bool = Field(False, description="Copy the output scripture to the system clipboard.")
    contrast: Optional[float] = Field(None, description="Enhance contrast by a factor (e.g., 1.5).")
    colors: Optional[int] = Field(None, description="Quantize the image to a specific number of colors.")


class GnosisRequest(BaseRequest):
    """A plea to discover the Gnostic Void of a blueprint."""
    blueprint_path: Path


class HashRequest(BaseRequest):
    """A plea to forge a cryptographic seal."""
    file_path: Path
    algo: str = "sha256"


class DoctorRequest(BaseRequest):
    """A plea to conduct a health inquest upon the local toolchain."""
    pass


class ChronicleRequest(BaseRequest):
    """A plea to commune with the Gnostic Ledger of past rites."""
    chronicle_command: str
    transaction_id: Optional[str] = None


class PackRequest(BaseRequest):
    """A plea to encapsulate an archetype into a distributable vessel."""
    source_path: Path
    output: Optional[Path] = None

class BannerRequest(BaseRequest):
    """A plea to forge a textual sigil."""
    text: str = "SCAFFOLD"
    font: str = "standard"
    output_path: Optional[str] = None

class UpgradeRequest(BaseRequest):
    """A plea for the Phoenix Protocol."""
    from_template: str
    force: bool = False

class SeedRequest(BaseRequest):
    """A plea for the Demiurge to populate the void."""
    count: int = 10
    output: str = "seed_data.json"

class CanonRequest(BaseRequest):
    """A plea for the Canonizer to judge architectural purity."""
    rules_path: str = "scaffold.rules.yaml"


class VectorRequest(BaseRequest):
    """
    =================================================================================
    == THE VESSEL OF SEMANTIC RECALL (V-Ω-HYBRID-RAG-ENABLED)                      ==
    =================================================================================
    @gnosis:title VectorRequest
    @gnosis:summary The unified command vessel for the Vector Cortex (RAG).
    @gnosis:LIF 1,000,000,000,000

    This vessel is the plea to the Vector Librarian, capable of commanding the
    ingestion of reality (`index`), the cleansing of memory (`clear`), or the
    semantic inquiry of a query (`query`). It is now fully equipped with RAG
    control parameters.
    =================================================================================
    """
    vector_command: str = Field(..., description="The rite to perform: 'index', 'query', or 'clear'.")
    query_text: Optional[str] = Field(None,
                                      description="The natural language concept to search for (required for 'query').")

    # --- Indexing and Query Control ---
    target_dir: Optional[str] = Field(None, description="The directory to scan for indexing (default: project root).")
    limit: int = Field(5, description="The maximum number of semantic shards to retrieve.")
    threshold: float = Field(0.75, description="The minimum required cosine similarity score (0.0 to 1.0).")
    force_reindex: bool = Field(False, description="Forces a full scan and re-embed, bypassing the index cache.")


class DeployRequest(BaseRequest):
    """
    A plea to the Celestial Forge to weave deployment scriptures.
    """
    __gnostic_requirements__ = {"docker", "helm"} # Declares its needs

    output_dir: str = "k8s"
    format: str = "helm"
    environment: str = "staging"
    tag: Optional[str] = None


class ProphesyRequest(BaseRequest):
    target_path: str = "."

class SecretsRequest(BaseRequest):
    action: str  # rotate
    target: str = ".env"

class KeyringRequest(BaseRequest):
    keyring_command: str # list, add, remove
    key_id: Optional[str] = None
    key_file: Optional[Path] = None

class SBOMRequest(BaseRequest):
    output: str = "sbom.spdx.json"

class FreezeRequest(BaseRequest):
    """A plea to forge the Dependency Time-Capsule."""
    deep: bool = Field(True, description="Ensures all dependencies are captured.")


class HolographRequest(BaseRequest):
    """A plea to forge the Environment Hologram."""
    output: Optional[str] = Field(None, description="The output path for the hologram.json file.")

class SignatureRequest(BaseRequest):
    """A plea to manage the Architect's Fingerprint."""
    signature_command: str = Field(description="The rite to perform: 'learn' or 'verify'.")
    threshold: float = Field(0.7, description="The confidence threshold for verification.")

class SaveRequest(BaseRequest):
    """A plea to the Neural Scribe to save the current work."""
    intent: str = Field(description="The high-level intent of the changes.")

class ReplRequest(BaseRequest):
    """A plea to awaken the Polyglot Conduit."""
    pass

class BiomeRequest(BaseRequest):
    """
    A plea to visualize the codebase as a living 3D terrain.
    """
    target: str = "."
    port: int = 8080
    theme: str = "cyberpunk"  # cyberpunk, synthwave, engineering
    threshold_complexity: int = 10  # Height scale factor
    threshold_churn: int = 50       # Heat scale factor


class ResonateRequest(BaseRequest):
    query: str
    limit: int = 5
    reindex: bool = False


class MRIRequest(BaseRequest):
    pass


class GhostRequest(BaseRequest):
    exorcise: bool = False


class BusFactorRequest(BaseRequest):
    """
    A plea to calculate the fragility of knowledge distribution.
    """
    threshold: float = 0.7  # Sensitivity (0.0 to 1.0)
    limit: int = 10  # Show top N risks





class BridgeRequest(BaseRequest):
    """A plea to forge a link between two tongues (FFI)."""
    source_lang: str = "rust"
    target_lang: str = "python"
    entry_point: str  # Path to the struct/class to bridge

class IsolateRequest(BaseRequest):
    """A plea to execute a command within a hermetic security ward."""
    command_to_run: str
    allow_hosts: List[str] = ["pypi.org", "files.pythonhosted.org", "registry.npmjs.org"]
    audit_only: bool = False

class ChaosGameRequest(BaseRequest):
    """A plea to initiate the Gamified Resilience Loop."""
    interval: int = 1800  # seconds (30 mins)
    lives: int = 3
    mode: str = "standard"  # standard, hardcore (no git recovery)

class TranslateRequest(BaseRequest):
    """A plea to transmute the soul of code from one tongue to another."""
    source_path: str
    target_lang: str
    source_lang: str = "auto"


class OptimizeCIRequest(BaseRequest):
    """
    A plea for the CI pipeline to rewrite its own DNA based on past performance.
    """
    workflow_path: str = ".github/workflows/main.yml"
    stats_file: Optional[str] = None  # JSON file with step durations
    strategy: str = "aggressive"  # aggressive (sharding), conservative (caching)


class HolographicBlueprintRequest(BaseRequest):
    """
    A plea to digitize a physical project into a pure .scaffold scripture.
    """
    target_dir: str = "."
    output_file: str = "hologram.scaffold"
    full_fidelity: bool = True  # Include all content, not just structure


class SemanticMountRequest(BaseRequest):
    """
    A plea to mount the project's Gnostic Soul as a virtual filesystem.
    """
    mount_point: str
    foreground: bool = True


class TelepathyRequest(BaseRequest):
    """
    A plea to awaken the Clipboard Sentinel.
    """
    auto_format: bool = True
    save_dir: str = "snippets"


class OptimizeBlueprintRequest(BaseRequest):
    """
    A plea for the Blueprint to evolve based on historical usage patterns.
    """
    target_blueprint: str = "scaffold.scaffold"
    threshold: float = 0.9  # 90% consistency required to trigger mutation
    auto_apply: bool = False


class MuseRequest(BaseRequest):
    """
    A plea for the Engine to prophesy the next logical step.
    """
    context_file: Optional[str] = None  # The file you just touched/created
    threshold: float = 0.3  # Minimum confidence to speak
    auto_draft: bool = False  # If True, creates the file as .draft


class SemDiffRequest(BaseRequest):
    """
    A plea to perceive the semantic divergence between two realities.
    """
    target: str = "."  # File or Directory
    reference: str = "HEAD"  # Git ref (HEAD, main, commit_hash)
    format: str = "table"  # table, json


class ForgeArtisanRequest(BaseRequest):
    """
    A plea to forge a new Artisan class and its Gnostic kin.
    """
    artisan_name: str  # e.g., "deploy" or "database_migrate"
    description: str = "A new artisan for the Scaffold cosmos."


class LintBlueprintRequest(BaseRequest):
    """
    A plea to verify the structural purity of a .scaffold scripture.
    """
    target: str  # Path to the blueprint file


class MockRequest(BaseRequest):
    """
    A plea to materialize a temporary reality for testing purposes.
    """
    spec: str  # e.g., "src/main.py,tests/test_main.py,README.md"
    root: Optional[str] = None  # Override target dir


class GuiRequest(BaseRequest):
    """
    A plea to summon the Ephemeral Command Palette.
    """
    initial_filter: Optional[str] = None  # Pre-fill the search box


class ExposeRequest(BaseRequest):
    """
    A plea to open a wormhole to the internet.
    """
    port: int
    provider: str = "localhost.run"  # or 'serveo'
    subdomain: Optional[str] = None


class SgrepRequest(BaseRequest):
    """
    A plea for Semantic Search.
    """
    pattern: str
    type: str = "any"  # function, class, variable, import
    show_code: bool = True




class AliasRequest(BaseRequest):
    """
    A plea to manage the Grimoire of Shortcuts.
    """
    alias_command: str  # add, list, remove
    name: Optional[str] = None
    expansion: Optional[str] = None


class QRRequest(BaseRequest):
    """
    A plea to open a visual portal to the local sanctum.
    """
    port: int


class ContextFreezeRequest(BaseRequest):
    """
    A plea to snapshot the current environmental state for debugging.
    """
    output_file: Optional[str] = "debug_context.json"
    include_env: bool = False  # Include safe env vars?


class BenchRequest(BaseRequest):
    """
    A plea to gauge the vitality of the host machine.
    """
    suites: List[str] = Field(default_factory=lambda: ["cpu", "disk", "net"])


class PurgeRequest(BaseRequest):
    """
    A plea to annihilate generated artifacts (node_modules, venv, etc).
    """
    target: str = "."
    dry_run: bool = False
    force: bool = False
    threshold_mb: int = 0  # Only show/delete if larger than X MB


class MatrixRequest(BaseRequest):
    """
    A plea to visualize the dependency graph and version conflicts.
    """
    scope: str = "all"  # all, production, dev
    format: str = "table"  # table, json, tree


class TodoRequest(BaseRequest):
    """
    A plea to harvest technical debt markers from the codebase.
    """
    path: str = "."
    author: Optional[str] = None  # Filter by git author
    format: str = "table"  # table, json, csv
    blame: bool = True  # Enable git blame lookup (slower)



class WithSecretsRequest(BaseRequest):
    """
    A plea to conduct a rite within a sanctum of ephemeral secrets.
    """
    provider: str = "1password"
    secrets: List[str] = Field(..., description="List of secret keys or references to fetch.")
    command: List[str] = Field(..., description="The command to execute with the injected secrets.")


# --- NEW REALITY: THE ASTROLABE ---
class AstrolabeRequest(BaseRequest):
    """A plea to open the Tree-sitter Workbench."""
    target_file: str

# --- NEW REALITY: THE WATCHMAN ---
class WatchmanRequest(BaseRequest):
    """A plea to set a vigil on the filesystem."""
    glob_pattern: str
    command_to_run: str
    debounce: float = 0.5

# --- NEW REALITY: THE AUDITOR ---
class AuditRequest(BaseRequest):
    """A plea to audit covenants (licenses)."""
    audit_target: str = "licenses" # Future expansion: 'security', 'quality'
    fail_on_heresy: bool = False


class NeuralRequest(BaseRequest):
    """
    A plea to enter the Synaptic Console for AI management.
    """
    command: str = "manage" # manage, test, list

class MountRequest(BaseRequest):
    """
    =============================================================================
    == THE PLEA OF THE REALITY BINDER                                          ==
    =============================================================================
    A plea to mount the Gnostic Cortex as a virtual filesystem, making the
    project's semantic soul tangible in the mortal realm.
    """
    mount_point: str = Field(
        "gnostic_fs",
        description="The local directory path to materialize the virtual filesystem."
    )



class ToolRequest(BaseRequest):
    """
    =================================================================================
    == THE UNIVERSAL GATEWAY VESSEL (V-Ω-ETERNAL-POLYMORPH)                        ==
    =================================================================================
    The polymorphic soul of the `tool` command. It is a union of all possible
    arguments for every specialist tool artisan, allowing the ToolArtisan conductor
    to perform its sacred Gnostic Triage.
    =================================================================================
    """
    # The Core Triage Key
    tool_command: str = Field(description="The specific tool rite to conduct (e.g., 'sbom', 'hash').")

    # --- Gnosis for the `ascii` Scribe ---
    image_path: Optional[Path] = Field(None, description="Path to the source image for ASCII transmutation.")
    width: int = Field(80, description="The target width of the ASCII art in characters.")
    charset: str = Field("detailed", description="The character set to use for rendering.")
    style: str = Field("color", description="The rendering style ('color' or 'mono').")
    invert: bool = Field(False, description="Invert the luminosity for the character map.")
    contrast: Optional[float] = Field(None, description="Apply a contrast enhancement factor.")
    colors: Optional[int] = Field(None, description="Quantize the image to a specific number of colors.")
    lang: str = Field("python", description="The output language for the generated scripture ('python', 'js', 'raw').")
    var_name: str = Field("get_sigil", description="The variable or function name for the generated scripture.")
    no_function: bool = Field(False, description="Output a raw variable assignment instead of a function.")
    clipboard: bool = Field(False, description="Copy the output scripture to the clipboard instead of printing.")
    append_to: Optional[Path] = Field(None, description="Path to a file where the output should be grafted.")
    marker: str = Field("# GNOSTIC_SIGIL_INJECTION", description="The marker to find for the Alchemical Graft.")

    # --- Gnosis for the `banner` Herald ---
    text: Optional[str] = Field(None, description="The text to render as a banner.")
    font: Optional[str] = Field(None, description="The Figlet font to use for the banner.")
    output_path: Optional[str] = Field(None, description="The file path to save the banner to.")

    # --- Gnosis for the `hash` Sealer ---
    file_path: Optional[Path] = Field(None, description="The path to the file to be hashed.")
    algo: str = Field("sha256", description="The hashing algorithm to use (e.g., 'sha256', 'md5').")

    # --- Gnosis for the `keyring` Keeper ---
    keyring_command: Optional[str] = Field(None, description="The keyring rite to perform ('list', 'add').")
    key_file: Optional[Path] = Field(None, description="Path to the public key file to add.")

    # --- Gnosis for the `pack` Architect ---
    source_path: Optional[Path] = Field(None, description="The source directory of the archetype to pack.")
    # `output_path` is already defined for `banner`

    # --- Gnosis for the `sbom` Scribe ---
    output: Optional[str] = Field("sbom.spdx.json", description="The output file for the Software Bill of Materials.")

    # --- Gnosis for the `secrets` Keymaster ---
    action: Optional[str] = Field(None, description="The secret management action to perform ('rotate').")
    target: Optional[str] = Field(".env", description="The target .env file for secret operations.")


class ReadSoulRequest(BaseRequest):
    """A plea to read the raw content of a single scripture."""
    path_to_scripture: str

class QueryRequest(BaseRequest):
    """
    A plea to the Gnostic Emissary, now ascended to carry a pure, structured
    Gnostic plea instead of a profane string.
    """
    query: Dict[str, Any]  # ★★★ THE APOTHEOSIS ★★★
    json_output: bool = Field(False, alias='json')


class ArchitectRequest(BaseRequest):
    """
    A plea to the Gnostic Architect.
    """
    prompt: str
    """The natural language intent (e.g., 'Add a user authentication module')."""

    interactive: bool = True
    """Whether to engage in a confirmation dialogue before materialization."""

class ChangelogRequest(BaseRequest):
    """A plea to the Chronicle Scribe."""
    from_ref: Optional[str] = Field(None, description="The Git ref (tag, commit) to start the changelog from. Defaults to the latest tag.")
    next_version: Optional[str] = Field(None, description="The version number to use for the new changelog entry.")
    output_file: str = Field("CHANGELOG.md", description="The path to the changelog file to update.")


class IgnoreRequest(BaseRequest):
    """A plea to the Gatekeeper of Aversion."""
    templates: List[str] = Field(default_factory=list, description="List of gitignore.io templates to fetch.")
    append: bool = Field(False, description="If true, appends to the existing .gitignore instead of overwriting.")


class SnippetRequest(BaseRequest):
    """A plea to the Fragment Keeper."""
    snippet_command: str = Field(..., description="The rite to perform (list, save, load, delete).")
    name: Optional[str] = Field(None, description="The sacred name of the snippet.")
    source_file: Optional[str] = Field(None, description="Path to a file to save as a snippet.")
    clipboard: bool = Field(False, description="Use the system clipboard as the source or destination.")


class ArchitecturalAuditRequest(BaseRequest):
    """A plea to the Gnostic Adjudicator to verify architectural laws."""
    audit_target: str = Field(default="arch", description="The specific audit to run.")

class AgentRequest(BaseRequest):
    """
    =============================================================================
    == THE VESSEL OF AGENCY (V-Ω-AUTONOMOUS-MISSION-ASCENDED)                   ==
    =============================================================================
    Carries the Architect's high-level mission for the autonomous Agent,
    now with a vow of interactivity to enable the Guardian's Veto.
    """
    mission: str = Field(..., description="The natural language mission for the Agent to accomplish.")
    interactive: bool = Field(True, description="If True, the Agent will pause for the Architect's approval before executing a plan.")


# In interfaces/requests.py
# Modify the ScribeRequest class

class ScribeRequest(BaseRequest):
    """
    =============================================================================
    == THE VESSEL OF PROPHECY (V-Ω-POLYGLOT-ASCENDED)                          ==
    =============================================================================
    Carries the Architect's architectural plea to the Scribe Pantheon, now with
    the Gnosis to specify which sacred tongue the prophecy should be written in.
    """
    plea: str = Field(..., description="The natural language architectural intent to be transmuted into a scripture.")

    # --- THE ASCENSION: THE VOW OF TONGUES ---
    language: str = Field(
        "scaffold",
        description="The sacred tongue of the prophecy: 'scaffold' (Form), 'symphony' (Will), or 'arch' (Unified Monad)."
    )
    # -----------------------------------------

    output_path: Optional[str] = Field(None, description="Optional path to save the generated scripture.")
    interactive: bool = Field(True,
                              description="If true, the Scribe will offer to execute the scripture after forging it.")


class TrainRequest(BaseRequest):
    """
    =============================================================================
    == THE VESSEL OF ASCENSION (V-Ω-MODEL-TRAINING)                            ==
    =============================================================================
    Carries the Architect's will to fine-tune an AI model upon a corpus of Gnosis.
    """
    # Source of Wisdom
    corpus_path: str = Field(".", description="Path to the source code or documents to learn from.")

    # The Student
    base_model: str = Field("unsloth/llama-3-8b-bnb-4bit", description="The base model to fine-tune (HuggingFace ID).")

    # The New Identity
    output_model_name: str = Field("scaffold-lora-v1", description="The name of the resulting adapter/model.")

    # Training Parameters
    provider: str = Field("huggingface", description="The training backend (huggingface, ollama, vertex).")
    epochs: int = Field(1, description="Number of training cycles.")
    batch_size: int = Field(2, description="Training batch size.")
    learning_rate: float = Field(2e-4, description="The rate of synaptic plasticity.")

    # Synthetic Data Generation
    generate_instructions: bool = Field(True, description="Use the AIEngine to hallucinate instructions for raw code.")
    limit_samples: Optional[int] = Field(None, description="Limit the number of training samples (for testing).")


class DataRequest(BaseRequest):
    """
    A plea to the Alchemist of State.
    Manages the fluid essence of the application (Database & State).
    """
    data_command: Literal["clone", "snapshot", "seed"] = Field(
        ..., description="The specific alchemical rite to perform."
    )
    source: Optional[str] = Field(None, description="Source connection string or path.")
    destination: Optional[str] = Field(None, description="Destination path.")
    snapshot_name: Optional[str] = Field(None, description="Name of the state freeze.")
    anonymize: bool = Field(True, description="If True, masks PII during cloning.")


class CodexRequest(BaseRequest):
    """
    A plea to the Living Wiki.
    Forges self-verifying documentation and architectural maps.
    """
    codex_command: Literal["build", "verify", "cartography"] = Field(
        ..., description="The rite of documentation."
    )
    output_dir: str = Field("docs", description="Target directory for the Codex.")
    serve: bool = Field(False, description="If True, serves the Codex locally after building.")


class ReviewRequest(BaseRequest):
    """
    A plea to the Sentinel's Tribunal.
     AI-driven adjudication of code changes before they enter the Chronicle.
    """
    review_command: Literal["adjudicate"] = "adjudicate"
    socratic_mode: bool = Field(
        False,
        description="If True, the AI asks guiding questions instead of flagging errors."
    )
    focus_files: Optional[List[str]] = Field(None, description="Specific files to review (defaults to staged).")

class LFGRequest(BaseRequest):
    """
    A plea to the Logic Flow Graph Engine.
    Requests the visualization of control flow within a Blueprint or Source Code.
    """
    target: str = Field(..., description="The path to the blueprint (.scaffold/.symphony) or source code file/directory.")
    mode: Literal["blueprint", "codebase"] = Field("blueprint", description="The mode of perception.")
    format: Literal["mermaid", "json"] = Field("mermaid", description="The output format.")
    output_path: Optional[str] = Field(None, description="Where to inscribe the graph.")

class AkashaRequest(BaseRequest):
    """
    A plea to the Global Memory of the Cosmos.
    """
    akasha_command: Literal["query", "stats", "purge", "learn"] = Field(
        ..., description="The rite to perform on the global memory."
    )
    query: Optional[str] = Field(None, description="The natural language query for wisdom recall.")
    source_path: Optional[str] = Field(None, description="Path to a file or directory to manually enshrine.")


class GuildRequest(BaseRequest):
    """
    A plea to the Guild Nexus.
    Manages the federation of Gnosis across the cosmos.
    """
    guild_command: Literal["publish", "join", "update", "list"] = Field(
        ..., description="The rite of federation."
    )
    target: Optional[str] = Field(None, description="The archetype to publish or the guild URI to join.")
    name: Optional[str] = Field(None, description="The alias for the guild subscription (e.g. '@my-team').")


class MimicRequest(BaseRequest):
    """
    A plea to the Simulacrum.
    Materializes an ephemeral API from a static type definition.
    """
    source_path: str = Field(...,
                             description="The path to the source definition (Pydantic model, SQL schema, or TS Interface).")
    port: int = Field(8000, description="The port to bind the ephemeral reality to.")
    framework: Literal["fastapi", "express"] = Field("fastapi", description="The soul of the mock server.")
    watch: bool = Field(True, description="If True, regenerates the simulacrum when the source changes.")


class FusionRequest(BaseRequest):
    """
    A plea to the Fusion Core.
    NOW ASCENDED: Handles both Cache Management (Legacy) and Compilation (New).
    """
    # Expanded commands to include build rites
    fusion_command: Literal["list", "clean", "bind", "compile"] = Field(
        ..., description="The fusion rite to perform."
    )
    # New fields for the Builder
    source: Optional[str] = Field(None, description="The source file (e.g., 'src/fast_math.rs').")
    target_lang: Literal["python", "node"] = Field("python", description="The host language to bind into.")
    output_dir: Optional[str] = Field(None, description="Where to place the compiled artifact.")


"""
=================================================================================
== THE KINETIC SHADOW REQUEST (V-Ω-TOTALITY-FINAL-V21-SINGULARITY)             ==
=================================================================================
This scripture defines the 'Will of the Architect' for materializing a 
parallel, functional, and rendered reality within the Shadow Dimension.
=================================================================================
"""


# ==============================================================================
# == THE SHADOW CLONE SCHEMA (V-Ω-TOTALITY-V100)                              ==
# ==============================================================================

class ShadowCommand(str, Enum):
    """The Verbs of Reality Manipulation."""
    SPAWN = "spawn"  # Create a new reality
    VANISH = "vanish"  # Destroy a reality
    LIST = "list"  # Census
    STATUS = "status"  # Health check
    LOGS = "logs"  # Forensic read
    HIBERNATE = "hibernate"  # Freeze state


class CloneStrategy(str, Enum):
    """The Physics of Materialization."""
    GIT_WORKTREE = "git_worktree"  # Fast, requires clean git state
    PHYSICAL_COPY = "physical_copy"  # Robust, slower, works on dirty state
    HYBRID = "hybrid"  # Try Worktree, fallback to Copy


class ShadowCloneRequest(BaseRequest):
    """
    =============================================================================
    == THE SHADOW REQUEST (V-Ω-CONTRACT-ASCENDED)                              ==
    =============================================================================
    LIF: 10,000,000,000 | The Immutable Law of Fission.
    Defines exactly how a parallel reality should be forged.
    """
    model_config = ConfigDict(extra='ignore', arbitrary_types_allowed=True)

    # --- 1. THE VERB (INTENT) ---
    shadow_command: ShadowCommand = Field(
        ...,
        description="The rite to perform on the Shadow Realm."
    )

    # --- 2. THE ANCHOR (LOCATION) ---
    # Inherited from BaseRequest, but we add a validator to handle 'cwd' alias
    # project_root: str

    # --- 3. THE IDENTITY (NAMING) ---
    label: str = Field(
        default="experiment",
        pattern=r"^[a-zA-Z0-9_\-]+$",
        description="Human-readable tag for this reality (e.g. 'feature-x')."
    )

    target_ref: str = Field(
        default="HEAD",
        description="Git reference (branch/hash) to clone from."
    )

    target_id: Optional[str] = Field(
        default=None,
        description="Specific Shadow ID to target for Vanish/Status rites."
    )

    owner: str = Field(
        default="architect",
        description="The entity responsible for this reality."
    )

    # --- 4. THE PHYSICS (CONFIGURATION) ---
    strategy: CloneStrategy = Field(
        default=CloneStrategy.HYBRID,
        description="The method of materialization."
    )


    port: int = Field(
        default=0,
        ge=0,
        le=65535,
        description="The port to bind. 0 = Divine a free port automatically."
    )

    # --- 5. THE SOUL (RUNTIME) ---
    custom_command: Optional[str] = Field(
        default=None,
        description="Override the detected startup command (e.g., 'npm run dev')."
    )

    variables: Dict[str, str] = Field(
        default_factory=dict,
        description="Environment variables to inject into the Shadow's .env file."
    )

    # [ASCENSION 4]: AUTO_PROVISION
    auto_provision: bool = Field(
        default=True,
        description="If True, performs Lung Transplantation (node_modules linking)."
    )

    # --- VALIDATORS ---

    @field_validator('project_root', mode='before')
    @classmethod
    def canonize_root(cls, v: Any, info: Any) -> str:
        """
        [ASCENSION 2]: PATH CANONIZATION
        Resolves '~', normalizes slashes, and handles the 'cwd' alias.
        """
        # Handle alias
        if v is None:
            # Look for 'cwd' in the raw data if project_root is missing
            values = info.data if hasattr(info, 'data') else {}
            if 'cwd' in values:
                v = values['cwd']

        if not v:
            return "."

        # Expand and Normalize
        path_str = str(v)
        try:
            expanded = Path(path_str).expanduser().resolve()
            return expanded.as_posix()
        except Exception:
            return path_str.replace('\\', '/')

    @model_validator(mode='before')
    @classmethod
    def alias_cwd_to_root(cls, data: Any) -> Any:
        """
        [ASCENSION 3]: DIALECT TRANSLATION
        Maps 'cwd' -> 'project_root' for clients that use shell terminology.
        """
        if isinstance(data, dict):
            if 'cwd' in data and 'project_root' not in data:
                data['project_root'] = data['cwd']

            # Map string command to Enum if possible
            if 'shadow_command' in data and isinstance(data['shadow_command'], str):
                try:
                    # Normalize 'spawn' -> ShadowCommand.SPAWN
                    data['shadow_command'] = ShadowCommand(data['shadow_command'].lower())
                except ValueError:
                    pass  # Let Pydantic validation fail natively for clear errors

        return data


# == END OF SCRIPTURE ==

class GardenRequest(BaseRequest):
    """
    A plea to the Entropy Garden.
    """
    garden_command: Literal["scan", "prune", "report"] = Field(
        "scan", description="The gardening rite."
    )
    aggressiveness: int = Field(1, description="1=Files Only, 3=Symbols (Safe), 5=Ruthless.")
    focus_path: Optional[str] = Field(None, description="Limit the garden walk to a specific path.")

class EvolveRequest(BaseRequest):
    """
    A plea to the Schema Engine.
    Synchronizes the Object Model (Code) with the Persistent State (DB).
    """
    evolve_command: Literal["check", "plan", "apply"] = Field(
        ..., description="The rite of evolution."
    )
    message: Optional[str] = Field(None, description="The rationale for this evolution (migration name).")
    target_env: str = Field("dev", description="The environment to target (dev, staging, prod).")
    
class ObserveRequest(BaseRequest):
    """
    A plea to the Neural Link.
    Summons the TUI Dashboard for runtime introspection.
    """
    target_pid: Optional[int] = Field(None, description="PID of the process to attach to (System Probe).")
    log_stream: Optional[str] = Field(None, description="Path to a log file to tail and visualize.")
    port: Optional[int] = Field(None, description="Port to sniff (Traffic Analysis).")
    demo: bool = Field(False, description="Run in simulation mode to demonstrate capabilities.")

class TeachRequest(BaseRequest):
    """
    A plea to the Tutorial Forge.
    Generates interactive coursework from the codebase.
    """
    teach_command: Literal["generate", "start", "verify"] = Field(
        ..., description="The pedagogical rite."
    )
    topic: Optional[str] = Field(None, description="Focus of the tutorial (e.g., 'auth', 'database').")
    difficulty: Literal["novice", "adept", "master"] = Field("novice", description="Complexity of the generated quests.")
    output_dir: str = Field(".scaffold/tutorial", description="Where to store the course materials.")


class LazarusRequest(BaseRequest):
    """
    A plea to the Lazarus Protocol.
    Automated debugging and self-healing.
    """
    error_context: Optional[str] = Field(None, description="The stack trace or error message.")
    command: Optional[str] = Field(None, description="The command that triggers the failure (e.g. 'pytest').")
    auto_apply: bool = Field(False, description="If True, apply the fix without confirmation.")

class FortressRequest(BaseRequest):
    """
    A plea to the Fortress.
    Security auditing and hardening.
    """
    scan_type: Literal["dependencies", "code", "full"] = Field("full", description="The scope of the audit.")
    fix: bool = Field(False, description="Attempt to auto-patch vulnerabilities.")

class BabelRequest(BaseRequest):
    """
    A plea to the Babel Engine.
    Transmutes code from one tongue to another.
    """
    source: str = Field(..., description="The source file or directory to port.")
    target_lang: Literal["rust", "go", "python", "typescript"] = Field(..., description="The destination language.")
    fusion_bind: bool = Field(False, description="If True, auto-generates FFI bindings (Fusion) for the new code.")


class HolocronRequest(BaseRequest):
    """
    A plea to the Holocron.
    Traces the causal chains of reality to define perfect context.
    """
    # [THE FIX] Added 'forge' to the allowed literals
    holocron_command: Literal["trace", "slice", "forge"] = Field(
        ..., description="The causal rite."
    )

    # 'entry_point' serves as the Symbol for trace/slice OR the Intent string for forge
    entry_point: str = Field(
        ..., description="The starting point (Symbol) or Problem Description."
    )

    input_data: Optional[str] = Field(None, description="JSON payload for dynamic tracing.")
    depth: int = Field(5, description="How deep to follow the white rabbit.")

    # [THE FIX] Added output_data to match the CLI 'dest' mapping
    output_data: Optional[str] = Field(None, description="Path to save the result.")

class OcularRequest(BaseRequest):
    """
    A plea to the Ocular Cortex.
    Visualizes the application and maps pixels back to code.
    """
    ocular_command: Literal["gaze", "audit", "align"] = Field(..., description="The visual rite.")
    url: str = Field("http://localhost:3000", description="The live URL to observe.")
    target_element: Optional[str] = Field(None, description="Selector or text description of the visual element.")
    design_mock: Optional[str] = Field(None, description="Path to an image file (Design Mock) to align against.")

class AetherRequest(BaseRequest):
    """
    A plea to the Neural Aether.
    Communes with the collective subconscious of all Architects.
    """
    aether_command: Literal["sync", "broadcast", "query"] = Field(..., description="The telepathic rite.")
    pattern_signature: Optional[str] = Field(None, description="Hash or signature of the problem/pattern.")
    privacy_level: Literal["high", "medium", "low"] = Field("high", description="Differential privacy setting.")


class DebateRequest(BaseRequest):
    """
    =================================================================================
    == THE SACRED PLEA FOR GNOSTIC DISCOURSE (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA)       ==
    =================================================================================
    @gnosis:title DebateRequest
    @gnosis:summary The pure, Pydantic-forged vessel for commanding the Hivemind.

    This is the unbreakable contract for the `debate` rite. It carries the topic of
    discourse, the chosen council of personas, and the sacred laws that will govern
    their communion. It is the one true key to unlocking the power of multi-agent
    AI consensus within the Scaffold cosmos.
    """
    model_config = ConfigDict(extra='allow')

    # --- I. The Core Gnostic Will ---
    workspace_command: str = Field(default="debate", description="The specific rite to be conducted by the Hivemind.")
    topic: str = Field(...,
                       description="The subject of the debate, either as a direct string or a path to a scripture of Gnosis.")

    # --- II. The Council of Personas ---
    personas: List[str] = Field(default_factory=lambda: ["architect", "security", "pragmatist"],
                                description="A list of the AI personas to summon for the debate council.")

    # --- III. The Laws of Communion ---
    rounds: int = Field(default=1, description="The number of rebuttal rounds to conduct after the initial arguments.")
    blind: bool = Field(default=False,
                        description="If True, personas do not see each other's arguments in the first round, forcing independent thought.")
    synthesize: bool = Field(default=True,
                             description="If True, a final AI Moderator will be summoned to analyze the transcript and forge a consensus.")
    interactive: bool = Field(default=False,
                              description="If True, the rite will pause after each round for the Architect's adjudication.")

    # --- IV. The Gnostic Chronicle ---
    output_path: Optional[str] = Field(default=None,
                                       description="Path to inscribe the final, complete transcript of the debate.")

    # --- V. The Alchemical Context ---
    variables: Dict[str, Any] = Field(default_factory=dict,
                                      description="Gnostic variables to bestow upon the debating council's context.")


class ConduitRequest(BaseRequest):
    """
    The sacred plea to awaken the Gnostic Cockpit (Celestial Bridge).
    """
    workspace_command: str = Field(default="conduit", description="The specific rite to be conducted.") # Corrected field name for consistency
    url: str = Field(default="https://aistudio.google.com/", description="The URL of the AI altar to embed.")
    port: int = Field(default=8787, description="The local port to serve the Gnostic Cockpit on.")


class ObservatoryRequest(BaseRequest):
    """
    A plea to manage the Gnostic Observatory.
    """
    obs_command: str = Field(..., description="The specific rite (list, add, switch, etc).")
    target: Optional[str] = Field(None, description="Path or ID of the project.")
    name: Optional[str] = Field(None, description="Alias for the project.")
    json_mode: bool = Field(False, description="Return pure JSON data (for Electron).")
    # For discover
    depth: int = 1

class ArchetypeRequest(BaseRequest):
    """
    =============================================================================
    == THE ARCHETYPE PLEA (V-Ω-SCHEMA)                                         ==
    =============================================================================
    LIF: 100x | The contract for discovering and managing patterns.
    """
    command: str = Field(default="list", description="The rite: list, inspect, pull, or sync.")
    target: Optional[str] = Field(None, description="The ID of the archetype or a Celestial URL.")
    output_path: Optional[str] = Field(None, description="Where to save a pulled archetype.")
    json_mode: bool = Field(default=False, description="Proclaim in machine-readable format.")



class GraphManifestRequest(BaseRequest):
    """
    A plea to the Genesis Architect.
    Carries the full topological definition of a reality to be forged.
    """
    project_root: str = Field(..., description="The physical anchor for manifestation")
    graph_data: Dict[str, Any] = Field(..., description="The full JSON payload of Nodes and Edges")
    dry_run: bool = Field(False, description="If true, returns a prophecy without inscription")

class PreviewRequest(BaseRequest):
    """The Plea to Gaze upon the Visual Soul."""
    path: str
    depth: int = 2  # How deep to traverse the component tree

class SimulateRequest(BaseRequest):
    content: Optional[str] = None
    target_file: Optional[str] = None
    language: Optional[str] = None
    timeout: int = 60
    env_vars: Optional[Dict[str, str]] = None
    # [ASCENSION]: The Holographic Lattice
    # Maps relative file paths to their content.
    virtual_context: Optional[Dict[str, str]] = None
    node_id: Optional[str] = None


class GrandSurveyRequest(BaseRequest):
    """
    A plea for the Omniscient Eye to gaze upon the workspace.
    Used by both CLI ('scaffold survey') and Daemon ('scaffold/grandSurvey').
    """
    rootUri: Optional[str] = Field(None, description="The workspace root URI to scan (RPC).")
    target_path: Optional[str] = Field(None, description="The CLI path argument.")

    # Internal Metadata (JSON '_meta' -> Python 'meta')
    meta: Optional[Dict[str, Any]] = Field(None, alias="_meta", description="Internal tracing metadata.")

    @model_validator(mode='after')
    def harmonize_targets(self) -> 'GrandSurveyRequest':
        # Unify CLI 'target_path' and RPC 'rootUri'
        if self.target_path and not self.rootUri:
            self.rootUri = f"file://{Path(self.target_path).resolve().as_posix()}"
        return self


# --- [ASCENSION 3]: THE CONFIGURATION PLEA ---
class ConfigChangeRequest(BaseRequest):
    """
    A plea to mutate the Neuro-Plasticity of the active Kernel.
    Primarily used via RPC 'workspace/didChangeConfiguration'.
    """
    settings: Dict[str, Any] = Field(..., description="The new configuration tree.")


class InitializeRequest(BaseRequest):
    """
    [THE FIRST BREATH]
    The LSP 'initialize' packet. Carries the client's capabilities and root URI.
    Now fully compliant with LSP 3.17 to prevent AttributeErrors.
    """
    processId: Optional[int] = None

    # [THE CURE]: Restored rootPath to satisfy the Node.js Client
    rootPath: Optional[str] = None
    rootUri: Optional[str] = None

    capabilities: Dict[str, Any] = Field(default_factory=dict)
    initializationOptions: Optional[Dict[str, Any]] = None
    trace: Optional[str] = "off"
    workspaceFolders: Optional[List[Any]] = None
    clientInfo: Optional[Dict[str, Any]] = None
    locale: Optional[str] = None  # Added for completeness


class PluginsRequest(BaseRequest):
    """
    [RITE: CENSUS]
    A plea to list all active capabilities (Artisans) within the Daemon.
    """
    command: str = "list"
    category: Optional[str] = None


class CliDispatchRequest(BaseRequest):
    """
    =============================================================================
    == THE CLI DISPATCH CONTRACT (V-Ω-SHIM-TRANSLATOR)                         ==
    =============================================================================
    A specialized vessel that carries raw command-line arguments from the
    Rust Shim into the warm heart of the Daemon.
    """
    args: List[str] = Field(..., description="The raw argv sequence from the shim.")
    auth_token: str = Field(..., description="The security token from the pulse file.")

class IndexRequest(BaseRequest):
    """
    The Plea for Knowledge.
    """
    force: bool = Field(False, description="Re-index all files regardless of cache state.")
    target_path: Optional[str] = Field(None, description="Specific file or directory to index.")


class SupabaseDomain(str, Enum):
    DATABASE = "database"
    AUTH = "auth"
    STORAGE = "storage"
    FUNCTION = "function"


class SupabaseRequest(BaseRequest):
    """
    =============================================================================
    == THE AKASHIC PLEA (V-Ω-TOTALITY-PERSISTENCE)                             ==
    =============================================================================
    LIF: ∞ | ROLE: DATA_CONTRACT | RANK: SOVEREIGN

    The unified, polymorphic vessel for all interactions with the Supabase Infrastructure.
    It segregates intent into three domains: DATABASE, AUTH, and STORAGE.

    ### THE 7 ASCENSIONS OF DATA:
    1.  **The Optionality Flag:** `optional=True` transforms a `single()` query into
        `maybe_single()`, returning `None` instead of crashing on empty results.
    2.  **Strict Domain Logic:** Validators ensure that a Database plea must have a Table,
        and a Storage plea must have a Bucket.
    3.  **The Counter:** Includes `count` strategy (exact/planned/estimated) for pagination.
    4.  **The Binary Carrier:** `file_source` allows streaming physical matter to Storage.
    5.  **The RPC Gateway:** First-class support for Stored Procedures (`rpc`) via `func_name`.
    6.  **Complex Filtering:** Accepts raw dictionary filters for advanced `PostgREST` syntax.
    7.  **Auth Expansion:** Supports admin actions like `generate_link` and `delete_user`.
    """
    model_config = ConfigDict(extra='ignore', populate_by_name=True)

    # --- 1. THE DOMAIN OF OPERATION ---
    domain: Literal["database", "auth", "storage", "function", "realtime"] = Field(
        ...,
        description="The realm of the Akashic Record to access."
    )

    # --- 2. DATABASE GNOSIS (TABLES & ROWS) ---
    table: Optional[str] = Field(None, description="Target table for DB operations.")

    method: Optional[Literal[
        "select", "insert", "update", "upsert", "delete", "rpc"
    ]] = Field(None, description="The SQL Verb.")

    # Query Modifiers
    select_columns: str = Field("*", description="Columns to retrieve (e.g. 'id, name, meta->key').")
    filters: Optional[Dict[str, Any]] = Field(None, description="Map of 'col': 'val' or 'col': 'op:val'.")
    order_by: Optional[str] = Field(None, description="Format: 'column:asc' or 'column:desc'.")
    limit: Optional[int] = Field(None, description="Pagination limit.")
    offset: Optional[int] = Field(None, description="Pagination offset.")

    # [THE CURE]: EXISTENTIAL MODIFIERS
    single: bool = Field(False, description="Expect exactly one result.")
    optional: bool = Field(False, description="If True, 'single' becomes 'maybe_single' (No error on 0 rows).")

    # Meta-Data
    count: Optional[Literal["exact", "planned", "estimated"]] = Field(None, description="Return total count strategy.")
    head: bool = Field(False, description="If True, return no data, only count/headers.")
    csv: bool = Field(False, description="If True, request response as CSV.")

    # RPC Specific
    func_name: Optional[str] = Field(None, description="Name of the Stored Procedure for 'rpc' method.")

    # --- 3. AUTH GNOSIS (IDENTITIES) ---
    auth_action: Optional[Literal[
        "get_user", "list_users", "create_user", "delete_user",
        "invite_user", "generate_link", "update_user", "sign_out"
    ]] = Field(None, description="The Identity Rite.")

    # Identity Data
    user_id: Optional[str] = Field(None, description="Target UUID of the soul.")
    email: Optional[str] = Field(None, description="Email coordinate.")
    password: Optional[str] = Field(None, description="Secret key for creation.")
    phone: Optional[str] = Field(None, description="E.164 phone coordinate.")

    # --- 4. STORAGE GNOSIS (ARTIFACTS) ---
    bucket: Optional[str] = Field(None, description="Target Storage Bucket.")
    storage_action: Optional[Literal[
        "upload", "download", "list", "remove", "move", "copy",
        "create_signed_url", "get_public_url"
    ]] = Field(None, description="The Archive Rite.")

    path: Optional[str] = Field(None, description="Path within the bucket.")
    file_source: Optional[Union[str, Path]] = Field(None, description="Local path to source file for upload.")
    destination: Optional[Union[str, Path]] = Field(None, description="Local path to save downloaded matter.")
    # =========================================================================
    # == [ASCENSION 1]: THE FORENSIC METADATA ENVELOPE (THE CURE)            ==
    # =========================================================================
    metadata: Dict[str, Any] = Field(
        default_factory=dict,
        description="Forensic context (trace_id, novalym_id) for the Audit Scribe."
    )
    # =========================================================================

    # Storage Options
    content_type: Optional[str] = Field(None, description="MIME type override.")
    upsert_file: bool = Field(False, description="Overwrite existing file.")
    expiry_seconds: int = Field(3600, description="TTL for signed URLs.")

    # --- 5. UNIVERSAL PAYLOAD (THE DATA) ---
    # Used for Insert/Update bodies, RPC params, or User Metadata
    data: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = Field(
        None,
        description="The Gnostic Payload (Rows for DB, Metadata for Auth)."
    )

    # =========================================================================
    # == THE RITES OF VALIDATION (LOGIC GATES)                               ==
    # =========================================================================

    @model_validator(mode='after')
    def validate_domain_constraints(self) -> 'SupabaseRequest':
        """
        Ensures the Plea matches the Domain.
        Prevents asking the Database for a File, or Storage for a User.
        """
        # 1. DATABASE GATE
        if self.domain == 'database':
            if not self.table and not self.func_name:
                # RPC calls might use func_name instead of table, but usually table is required for standard ops
                if self.method != 'rpc':
                    raise ValueError("Database Rite requires a 'table'.")
            if not self.method:
                raise ValueError("Database Rite requires a 'method'.")

        # 2. STORAGE GATE
        if self.domain == 'storage':
            if not self.bucket:
                raise ValueError("Storage Rite requires a 'bucket'.")
            if not self.storage_action:
                raise ValueError("Storage Rite requires a 'storage_action'.")

            if self.storage_action == 'upload' and not self.file_source:
                raise ValueError("Upload Rite requires 'file_source'.")

        # 3. AUTH GATE
        if self.domain == 'auth':
            if not self.auth_action:
                raise ValueError("Auth Rite requires an 'auth_action'.")

            if self.auth_action in ['get_user', 'delete_user'] and not self.user_id:
                raise ValueError(f"Auth Rite '{self.auth_action}' requires 'user_id'.")

        return self


class CommunicationRequest(BaseRequest):
    """
    [THE HIGH HERALD'S PLEA]
    A unified request to dispatch information across the ether.
    """
    # Routing
    channel: Literal["email", "sms", "chat"] = Field(..., description="The medium of transmission.")
    provider: Optional[str] = Field(None, description="Specific provider override (e.g., 'gmail', 'resend').")
    metadata: Dict[str, Any] = Field(default_factory=dict, description="Arbitrary context for middleware/Artisans.")
    # Destination
    recipient: Union[str, List[str]] = Field(..., description="Primary target(s).")
    cc: Optional[List[str]] = None
    bcc: Optional[List[str]] = None

    # Content
    subject: Optional[str] = None
    content: Optional[str] = Field(None, description="Raw text content.")
    template: Optional[str] = Field(None, description="Path to a Jinja2 template.")
    context: Dict[str, Any] = Field(default_factory=dict, description="Variables for the template.")

    # Artifacts
    attachments: List[str] = Field(default_factory=list, description="Paths to local files to attach.")

    # Metaphysics
    html: bool = True
    priority: str = "normal"


class NetworkProtocol(str, Enum):
    HTTP = "http"
    GRAPHQL = "graphql"
    WEBHOOK = "webhook"  # Specialized sending with signing


class NetworkRequest(BaseRequest):
    """
    [THE UNIVERSAL ADAPTER V2]
    A unified plea for interaction with the external digital ether.
    """
    # Routing
    protocol: NetworkProtocol = Field(default=NetworkProtocol.HTTP, description="Communication dialect.")
    url: str = Field(..., description="Target Endpoint.")
    method: str = Field("GET", description="HTTP Method (GET, POST, PUT, DELETE, PATCH).")

    # Payload
    headers: Dict[str, str] = Field(default_factory=dict)
    params: Dict[str, Any] = Field(default_factory=dict, description="Query parameters.")
    json_body: Optional[Dict[str, Any]] = Field(None, description="JSON payload.")
    data: Optional[Any] = Field(None, description="Raw body or Form data.")

    # GraphQL Specific
    query: Optional[str] = Field(None, description="GraphQL Query string.")
    variables: Optional[Dict[str, Any]] = Field(None, description="GraphQL Variables.")

    # Webhook Specific
    secret: Optional[str] = Field(None, description="Secret for HMAC signing.")
    signature_header: str = "X-Signature"

    # Configuration
    timeout: float = 10.0
    retries: int = 0
    auth: Optional[Dict[str, str]] = Field(
        None,
        description="Auth config. E.g. {'type': 'bearer', 'token': '...'} or {'type': 'basic', 'user': '...', 'pass': '...'}"
    )


class BillingEntity(str, Enum):
    CUSTOMER = "customer"
    SUBSCRIPTION = "subscription"
    PRODUCT = "product"
    PRICE = "price"
    INVOICE = "invoice"
    PORTAL = "portal"
    PAYMENT_LINK = "payment_link"
    EVENT = "event"  # For webhook verification


class BillingRequest(BaseRequest):
    """
    [THE TREASURY RITE V2]
    A unified plea to the Financial Sovereign (Stripe).
    """
    entity: BillingEntity = Field(..., description="The fiscal object to manipulate.")
    action: str = Field(..., pattern=r"^(create|retrieve|update|delete|list|search|finalize|void|pay|usage)$")

    # Context
    id: Optional[str] = Field(None, description="Target ID (cus_..., sub_...).")

    # Payload
    payload: Dict[str, Any] = Field(default_factory=dict, description="Stripe parameters (metadata, items, etc.).")

    # Advanced Tuning
    expand: List[str] = Field(default_factory=list,
                              description="Expand nested objects (e.g. ['customer', 'latest_invoice']).")
    limit: int = Field(10, description="Pagination limit for lists.")
    idempotency_key: Optional[str] = None

class StorageRequest(BaseRequest):
    """
    [THE ARCHIVE RITE] Manage heavy matter (Files/S3).
    """
    bucket: str = Field(..., description="Target bucket.")
    path: str = Field(..., description="File path in the cloud.")
    action: str = Field(..., pattern=r"^(upload|download|delete|sign_url)$")
    source_path: Optional[str] = Field(None, description="Local path for upload.")
    destination_path: Optional[str] = Field(None, description="Local path for download.")
    content_type: Optional[str] = None
    expiry_seconds: int = 3600


class CRMProvider(str, Enum):
    HUBSPOT = "hubspot"
    SALESFORCE = "salesforce"
    ZOHO = "zoho"


class CRMRequest(BaseRequest):
    """
    [THE DIPLOMAT'S PLEA]
    A unified interface for managing Customer Relationships across disparate systems.
    """
    provider: CRMProvider = Field(default=CRMProvider.HUBSPOT, description="Target System.")

    # Targeting
    entity: str = Field(..., pattern=r"^(contact|company|deal|ticket|product)$")
    action: str = Field(..., pattern=r"^(create|update|upsert|get|list|search|delete|associate)$")

    # Identity
    id: Optional[str] = Field(None, description="Native CRM ID (e.g. 12345).")
    match_key: Optional[str] = Field("email", description="Field to use for Upsert/Search deduplication.")
    match_value: Optional[str] = Field(None, description="Value to match against.")

    # Payload
    data: Dict[str, Any] = Field(default_factory=dict, description="Fields/Properties to write.")

    # Linking (The Web of Relations)
    # Example: {"to_entity": "company", "to_id": "9876"}
    associations: List[Dict[str, str]] = Field(default_factory=list, description="Links to forge after creation.")

    # Tuning
    limit: int = 10
    properties: List[str] = Field(default_factory=list, description="Specific fields to retrieve.")


# =============================================================================
# == SECTION I: THE NEURAL TAXONOMY (ENUMS)                                  ==
# =============================================================================

class AIProvider(str, Enum):
    """The Silicon Minds available to the Monolith."""
    OPENAI = "openai"
    AZURE = "azure"
    ANTHROPIC = "anthropic"
    GOOGLE = "google"
    LOCAL = "local"  # Ollama / LM Studio
    GROQ = "groq"  # Hyper-velocity inference
    PERPLEXITY = "perplexity"  # Search-grounded inference


class ModelStrategy(str, Enum):
    """Abstract strategies that resolve to concrete models at runtime."""
    SMART = "smart"  # GPT-4o / Claude 3.5 Sonnet / o1
    FAST = "fast"  # GPT-4o-mini / Haiku / Llama 3
    REASONING = "reasoning"  # o1-preview / o3 (Heavy Chain of Thought)
    CREATIVE = "creative"  # High temperature variants
    CODING = "coding"  # Claude 3.5 Sonnet / DeepSeek Coder


class RAGStrategy(str, Enum):
    """The method of memory retrieval."""
    NONE = "none"
    BASIC = "basic"  # Vector Similarity only
    HYBRID = "hybrid"  # Vector + Keyword (BM25)
    DEEP = "deep"  # Recursive / Graph-based traversal
    AGENTIC = "agentic"  # The AI decides what to search


# =============================================================================
# == SECTION II: THE GNOSTIC SUB-STRATA (COMPONENTS)                         ==
# =============================================================================

class MediaAsset(BaseModel):
    """
    [THE SENSORY INPUT]
    A container for non-textual matter (Images, Audio frames).
    """
    type: Literal["image_url", "image_base64", "audio_base64"] = "image_url"
    data: str = Field(..., description="The URL or Base64 string.")
    detail: Literal["auto", "low", "high"] = "auto"


class ToolConfig(BaseModel):
    """
    [THE KINETIC LIMB]
    Definition of a function the AI is allowed to execute.
    """
    name: str
    description: str
    parameters: Dict[str, Any]  # JSON Schema
    strict: bool = False  # OpenAI Strict Mode support


# =============================================================================
# == SECTION III: THE OMEGA INTELLIGENCE REQUEST                             ==
# =============================================================================

class IntelligenceRequest(BaseRequest):
    """
    =============================================================================
    == THE OMEGA INTELLIGENCE REQUEST (V-Ω-TOTALITY-V9000)                     ==
    =============================================================================
    LIF: INFINITY | ROLE: COGNITIVE_PAYLOAD_VESSEL | RANK: OMEGA_SOVEREIGN
    AUTH_CODE: Ω_NEURAL_REQ_2026_FINALIS

    The definitive, future-proof contract for summoning machine cognition.
    It contains pockets for every conceivable dimension of AI interaction:
    Text, Vision, Audio, Tooling, RAG, Forensics, and Economics.

    ### THE 12 ASCENSIONS OF THE SCHEMA:
    1.  **Metadata Sovereignty (THE CURE):** `metadata` is now a mandatory,
        pre-validated dictionary. The `AttributeError` is physically impossible.
    2.  **Multimodal Totality:** Support for `media_assets` list allows mixing
        text, images, and audio in a single prompt.
    3.  **Reasoning Physics:** Adds `reasoning_effort` (low/medium/high) for
        next-gen 'Thinking' models (o1/o3).
    4.  **Economic Circuit Breakers:** `budget_cap_usd` allows the request to
        self-terminate if the predicted cost is too high.
    5.  **Gnostic Context Injection:** A dedicated `context` dictionary for
        injecting RAG shards without polluting the `user_prompt` string manually.
    6.  **Safety & Compliance:** `safety_settings` dict for controlling
        guardrails (Gemini BlockNone vs OpenAI Moderation).
    7.  **Deterministic Anchoring:** `seed` field for reproducible outputs
        during regression testing.
    8.  **Tooling Orchestration:** First-class support for `tools`, `tool_choice`,
        and `parallel_tool_calls`.
    9.  **Achronal Trace Lineage:** `trace_id` is auto-generated if missing,
        binding the thought to the global causal chain.
    10. **Schema Enforcement:** `output_schema` field for forcing Structured Outputs
        (Pydantic/Zod) at the API level.
    11. **Provider Agnosticism:** `model` accepts abstract strategies ('smart')
        which the Provider resolves to concrete deployments.
    12. **The Finality Vow:** Extra fields are allowed (`extra='allow'`), ensuring
        this schema never breaks when providers release new parameters.
    """
    model_config = ConfigDict(
        extra='allow',
        populate_by_name=True,
        arbitrary_types_allowed=True,
        validate_assignment=True
    )

    # --- 1. THE CORE COGNITION (PROMPTS) ---
    system_prompt: Optional[str] = Field(
        default="You are a helpful Gnostic Assistant, an expert in software architecture.",
        description="The Constitutional Law / Persona of the Mind."
    )
    user_prompt: str = Field(
        ...,
        description="The kinetic query or instruction from the Architect."
    )

    # [ASCENSION 2]: LIST-BASED HISTORY
    # Allows passing a full chat history [user, assistant, user] for conversational continuity.
    messages: Optional[List[Dict[str, Any]]] = Field(
        default=None,
        description="Full conversation history. Overrides user_prompt/system_prompt if present."
    )

    # --- 2. MULTIMODAL SENSORY INPUT ---
    # Legacy fields for backward compatibility
    image_data: Optional[str] = Field(None, description="Legacy Base64 image.")
    image_url: Optional[str] = Field(None, description="Legacy Image URL.")

    # [ASCENSION 2]: THE MEDIA ARRAY
    media_assets: List[MediaAsset] = Field(
        default_factory=list,
        description="A phalanx of visual or audio inputs for the model."
    )

    # --- 3. ROUTING & STRATEGY ---
    provider: AIProvider = Field(default=AIProvider.OPENAI)
    model: str = Field(
        default=ModelStrategy.SMART,
        description="Target model ID or abstract strategy ('smart', 'fast')."
    )

    # --- 4. PHYSICS OF THOUGHT (HYPERPARAMETERS) ---
    temperature: float = Field(0.7, ge=0.0, le=2.0)
    max_tokens: int = Field(2048, ge=1)
    top_p: float = Field(1.0, ge=0.0, le=1.0)
    frequency_penalty: float = Field(0.0, ge=-2.0, le=2.0)
    presence_penalty: float = Field(0.0, ge=-2.0, le=2.0)

    # [ASCENSION 7]: DETERMINISM
    seed: Optional[int] = Field(None, description="The anchor for reproducible outputs.")

    # [ASCENSION 3]: REASONING EFFORT (o1/o3 support)
    reasoning_effort: Optional[Literal["low", "medium", "high"]] = Field(
        None,
        description="Thinking budget for reasoning models."
    )

    # --- 5. OUTPUT GOVERNANCE ---
    stream: bool = Field(default=False)
    json_mode: bool = Field(default=False, description="Enforce JSON object return.")

    # [ASCENSION 10]: STRICT SCHEMA
    output_schema: Optional[Dict[str, Any]] = Field(
        None,
        description="JSON Schema for Structured Outputs (strict mode)."
    )

    # --- 6. RAG & MEMORY STRATA ---
    use_rag: bool = Field(default=False)
    rag_strategy: RAGStrategy = Field(default=RAGStrategy.BASIC)

    # [ASCENSION 5]: CONTEXT INJECTION
    context: Dict[str, Any] = Field(
        default_factory=dict,
        description="Key-value pairs to be injected into the prompt via Jinja."
    )
    rag_filters: Optional[Dict[str, Any]] = Field(
        default=None,
        description="Metadata filters for the Vector Scry."
    )

    # --- 7. KINETIC TOOLS ---
    tools: List[ToolConfig] = Field(default_factory=list)
    tool_choice: Union[str, Dict[str, Any]] = Field(default="auto")
    parallel_tool_calls: bool = Field(default=True)

    # --- 8. FORENSICS, METADATA & ECONOMICS (THE CURE) ---
    # [ASCENSION 1]: THE METADATA ENVELOPE
    metadata: Dict[str, Any] = Field(
        default_factory=dict,
        description="The Forensic Sarcophagus. Holds trace_id, user_grade, and cost_center."
    )

    # [ASCENSION 9]: TRACE ID
    trace_id: str = Field(
        default="tr-void",
        description="The Silver Cord linking this thought to the Request."
    )

    # [ASCENSION 4]: FINANCIAL GUARD
    budget_cap_usd: float = Field(
        default=1.00,
        description="Hard stop if predicted cost exceeds this value."
    )
    cost_center: str = Field(
        default="GENERAL_COMPUTE",
        description="Ledger category for this spend."
    )

    # [ASCENSION 6]: SAFETY
    safety_settings: Dict[str, str] = Field(
        default_factory=dict,
        description="Provider-specific safety overrides (e.g. BLOCK_NONE)."
    )

    force: bool = Field(
        default=False,
        description="Sovereign Override to bypass budget/rate limits."
    )

    # =========================================================================
    # == THE RITE OF PRE-FLIGHT VALIDATION (THE FIX)                         ==
    # =========================================================================

    @model_validator(mode='before')
    @classmethod
    def forge_defaults(cls, data: Any) -> Any:
        """
        [THE GUARDIAN]: Ensures Metadata and Trace ID are never void.
        Heals the 'AttributeError' by physically injecting the dict if missing.
        """
        if isinstance(data, dict):
            # 1. HEAL METADATA FRACTURE
            if "metadata" not in data or data["metadata"] is None:
                data["metadata"] = {}

            # 2. TRACE ID HOISTING
            # If trace_id is at root, copy to metadata. If missing, gen new one.
            root_trace = data.get("trace_id")
            meta_trace = data["metadata"].get("trace_id")

            final_trace = root_trace or meta_trace or f"tr-ai-{uuid.uuid4().hex[:8]}"

            data["trace_id"] = final_trace
            data["metadata"]["trace_id"] = final_trace

            # 3. LEGACY IMAGE COMPATIBILITY
            # If legacy image fields exist, migrate them to media_assets
            if data.get("image_data"):
                assets = data.get("media_assets", [])
                assets.append({"type": "image_base64", "data": data["image_data"]})
                data["media_assets"] = assets

        return data

    @computed_field
    @property
    def fingerprint(self) -> str:
        """[ASCENSION 13]: Deterministic Hash of the Prompt Intent."""
        import hashlib
        core_content = f"{self.system_prompt}:{self.user_prompt}:{self.model}"
        return hashlib.sha256(core_content.encode()).hexdigest()

    def __repr__(self) -> str:
        return f"<Ω_INTELLIGENCE trace={self.trace_id} model={self.model} rag={self.use_rag}>"


class BrowserRequest(BaseRequest):
    """
    [THE NAVIGATOR'S PLEA]
    Command a headless browser to interact with the Living Web.
    """
    url: str = Field(..., description="Target URI.")
    action: str = Field(..., pattern=r"^(scrape|screenshot|pdf|interact)$")

    # Selectors & Interaction
    selector: Optional[str] = Field(None, description="CSS/XPath selector to target.")
    input_value: Optional[str] = Field(None, description="Text to type into inputs.")
    wait_for: Optional[str] = Field(None, description="Selector to wait for before acting.")

    # Extraction
    extract_fields: Optional[Dict[str, str]] = Field(None, description="Map of {key: selector} for scraping.")

    # Configuration
    headless: bool = True
    viewport: Dict[str, int] = Field(default_factory=lambda: {"width": 1280, "height": 720})
    timeout: float = 30.0


class DocumentFormat(str, Enum):
    PDF = "pdf"
    CSV = "csv"
    EXCEL = "xlsx"
    HTML = "html"


class DocumentRequest(BaseRequest):
    """
    [THE SCRIBE'S PLEA]
    Transmute structured data into physical documents, or ingest documents into data.
    """
    action: str = Field(..., pattern=r"^(generate|parse|convert|merge)$")
    format: DocumentFormat = Field(..., description="Target/Source format.")

    # Inputs
    source_path: Optional[str] = Field(None, description="Input file for parsing/conversion.")
    template_path: Optional[str] = Field(None, description="Jinja2 HTML template for PDF generation.")
    data: Optional[Union[List[Dict], Dict]] = Field(None, description="Data to inject into the document.")

    # Outputs
    output_path: Optional[str] = Field(None, description="Where to save the result.")

    # Options
    options: Dict[str, Any] = Field(default_factory=dict, description="Format-specific tuning (e.g. page_size).")


class WorkerRequest(BaseRequest):
    """
    [THE TASKMASTER'S PLEA]
    Dispatch logic to the background ethers (Queue).
    """
    queue: str = Field("default", description="Target queue name.")
    task: str = Field(..., description="Name of the function/task to execute.")
    args: List[Any] = Field(default_factory=list, description="Positional arguments.")
    kwargs: Dict[str, Any] = Field(default_factory=dict, description="Keyword arguments.")

    # Temporal Control
    delay_seconds: int = Field(0, description="Execute after delay.")
    schedule_at: Optional[datetime] = Field(None, description="Execute at specific time.")
    cron: Optional[str] = Field(None, description="Recurring schedule (CRON format).")

    # Resilience
    retries: int = Field(3, description="Max retry attempts.")
    timeout: int = Field(300, description="Execution timeout seconds.")


class VectorModel(str, Enum):
    OPENAI_ADA = "text-embedding-3-small"
    COHERE_V3 = "embed-english-v3.0"


class MemoryRequest(BaseRequest):
    """
    [THE CORTEX KEEPER'S PLEA]
    Manage Semantic Memory (Embeddings & Vector Search).
    """
    collection: str = Field(..., description="Logical grouping (Table/Namespace).")
    action: str = Field(..., pattern=r"^(upsert|query|delete|purge)$")

    # For Upsert
    text: Optional[Union[str, List[str]]] = Field(None, description="Raw text to embed and store.")
    metadata: Optional[Union[Dict, List[Dict]]] = Field(None, description="Payload to store with vectors.")
    ids: Optional[Union[str, List[str]]] = Field(None, description="Specific IDs (optional, auto-generated if void).")

    # For Query
    query_text: Optional[str] = Field(None, description="Concept to search for.")
    top_k: int = Field(5, description="Number of memories to recall.")
    threshold: float = Field(0.7, description="Minimum similarity score.")

    # Configuration
    model: VectorModel = Field(VectorModel.OPENAI_ADA, description="Embedding Model.")


class CacheRequest(BaseRequest):
    """
    =============================================================================
    == THE OMEGA CACHE REQUEST (V-Ω-TOTALITY-V110-HEALED)                      ==
    =============================================================================
    LIF: ∞ | ROLE: EPHEMERAL_STATE_VESSEL | RANK: LEGENDARY

    The definitive contract for all Stratum-8 (Redis) interactions.
    Healed of the 'AttributeError' heresy through Forensic Metadata Inception.
    """
    model_config = ConfigDict(extra='allow', populate_by_name=True)

    # --- 1. THE COORDINATES ---
    key: str = Field(..., description="The unique identifier in the Ephemeral Vault.")
    action: Literal["get", "set", "delete", "increment", "lock", "exists", "unlock", "expire"] = Field(
        ..., description="The kinetic rite to perform on the vault."
    )

    # --- 2. THE MATTER ---
    value: Optional[Any] = Field(
        default=None,
        description="The data-soul to store (Required for 'set' and 'lock')."
    )

    # --- 3. THE PHYSICS ---
    ttl: int = Field(
        default=3600,
        description="Time-to-live in seconds. 0 for eternity."
    )
    amount: int = Field(
        default=1,
        description="The delta for 'increment' operations."
    )

    # =========================================================================
    # == [ASCENSION 1]: THE FORENSIC METADATA ENVELOPE (THE CURE)            ==
    # =========================================================================
    # This slot is now mandatory for all requests to ensure 100% compatibility
    # with the Gnostic Middleware Spine (Audit Logging, Tracing, Governance).
    metadata: Dict[str, Any] = Field(
        default_factory=dict,
        description="Forensic context (trace_id, novalym_id, etc.) for the Audit Scribe."
    )

    # =========================================================================

    def __repr__(self) -> str:
        """PII-Safe representation for logs."""
        return f"<Cache:{self.action} key={self.key} trace={self.metadata.get('trace_id', 'None')}>"


class SheetProvider(str, Enum):
    GOOGLE = "google"
    AIRTABLE = "airtable"


class SheetRequest(BaseRequest):
    """
    [THE GRID MASTER'S PLEA]
    Interact with Spreadsheets and Smart Grids.
    """
    provider: SheetProvider = Field(default=SheetProvider.GOOGLE)
    action: str = Field(..., pattern=r"^(read|append|update|clear|create_tab)$")

    # Targeting
    base_id: str = Field(..., description="Spreadsheet ID or Airtable Base ID.")
    table_name: str = Field(..., description="Sheet name or Table name.")

    # Data
    rows: List[Dict[str, Any]] = Field(default_factory=list, description="Data rows.")
    row_id: Optional[str] = Field(None, description="Row ID for updates (Airtable only).")

    # Tuning
    range: Optional[str] = Field(None, description="A1 notation range (Google only).")
    value_input_option: str = Field("USER_ENTERED", description="Google: RAW or USER_ENTERED.")


class TwilioRequest(BaseRequest):
    """
    =============================================================================
    == THE TELEPHONIC VESSEL (V-Ω-OMNICHANNEL-GOD-OBJECT)                      ==
    =============================================================================
    LIF: ∞ | ROLE: CARRIER_INTENT | RANK: SOVEREIGN

    The one true vessel for all interactions with the Global Carrier Grid.
    It unifies Messaging, Provisioning, Intelligence, and Compliance into a
    single, polymorphic contract.
    """
    model_config = ConfigDict(extra='ignore', populate_by_name=True)

    # --- 1. THE RITE OF ACTION ---
    action: Literal[
        # Kinetic
        "send", "send_sms", "send_mms", "broadcast",
            # Infrastructure
        "search", "buy", "configure", "release", "update",
            # Intelligence
        "lookup", "validate",
            # Compliance (A2P 10DLC)
        "register_brand", "register_campaign", "link_number"
    ] = Field(..., description="The Telephonic Rite to perform.")

    # --- 2. KINETIC TARGETING (MESSAGING) ---
    to_number: Optional[str] = Field(None, alias="recipient", description="Target E.164 coordinate.")
    from_number: Optional[str] = Field(None, alias="sender", description="Origin E.164 coordinate.")
    messaging_service_sid: Optional[str] = Field(None, description="A2P Messaging Service SID (MG...).")

    body: Optional[str] = Field(None, alias="content", description="The text payload.")
    media_url: Optional[Union[str, List[str]]] = Field(None, description="List of media URLs for MMS.")

    # Advanced Kinetic Physics
    status_callback: Optional[str] = Field(None, description="Webhook for delivery confirmation.")
    validity_period: Optional[int] = Field(14400, description="Seconds before message expires (TTL).")
    schedule_type: Optional[Literal["fixed"]] = Field(None, description="For scheduled messages.")
    send_at: Optional[str] = Field(None, description="ISO8601 timestamp for scheduled delivery.")

    # --- 3. INFRASTRUCTURE SCRYING (PROVISIONING) ---
    country_code: str = Field("US", description="ISO 3166-1 alpha-2 Country Code (e.g., US, GB, DE).")
    area_code: Optional[str] = Field(None, description="3-digit regional prefix.")
    contains: Optional[str] = Field(None, description="Sequence of digits the number must contain.")
    limit: int = Field(5, description="Maximum number of results to scry.")

    # Capability Filters
    sms_enabled: bool = Field(True, description="Must support SMS.")
    mms_enabled: bool = Field(True, description="Must support MMS.")
    voice_enabled: bool = Field(True, description="Must support Voice.")

    # --- 4. ASSET MANAGEMENT (CONFIGURATION) ---
    phone_number: Optional[str] = Field(None, description="The E.164 number to act upon.")
    sid: Optional[str] = Field(None, description="The Twilio Resource SID (PN..., SM..., MG...).")
    friendly_name: Optional[str] = Field(None, description="Human-readable label for the asset.")

    # Webhook Bindings
    voice_url: Optional[str] = Field(None, description="Webhook for inbound calls.")
    sms_url: Optional[str] = Field(None, description="Webhook for inbound messages.")
    status_callback_method: Literal["POST", "GET"] = Field("POST", description="HTTP Method for webhooks.")

    # --- 5. INTELLIGENCE (LOOKUPS) ---
    include_name: bool = Field(False, description="Perform CNAM (Caller ID) lookup.")
    include_carrier: bool = Field(True, description="Perform HLR Carrier lookup.")

    # --- 6. REGULATORY COMPLIANCE (A2P 10DLC) ---
    # Identity
    legal_name: Optional[str] = Field(None, alias="business_name", description="Legal Business Name.")
    email: Optional[str] = Field(None, description="Contact email for compliance.")
    website: Optional[str] = Field(None, description="Business URL.")
    tax_id: Optional[str] = Field(None, alias="ein", description="EIN or Tax ID.")
    address_sid: Optional[str] = Field(None, description="Twilio Address SID (AD...).")

    # Campaign
    brand_sid: Optional[str] = Field(None, description="A2P Brand SID (BZ...).")
    use_case: Optional[str] = Field("LOW_VOLUME_MIXED", description="Campaign Use Case.")
    description: Optional[str] = Field(None, description="Campaign Description for carrier review.")
    sample_msgs: Optional[List[str]] = Field(None, description="Sample messages for compliance audit.")
    policy_sid: Optional[str] = Field(None, description="Regulatory Policy SID.")

    # --- 7. METAPHYSICS ---
    metadata: Dict[str, Any] = Field(default_factory=dict, description="Contextual Gnosis.")

    @field_validator('media_url', mode='before')
    @classmethod
    def unify_list(cls, v: Any) -> Optional[List[str]]:
        """Transmutes a single string into a list of strings."""
        if isinstance(v, str):
            return [v]
        return v

    @model_validator(mode='after')
    def validate_kinetics(self) -> 'TwilioRequest':
        """Ensures the Vessel is watertight based on the Rite."""
        action = self.action

        # Kinetic Validation
        if action in ['send', 'send_sms', 'send_mms']:
            if not self.to_number:
                raise ValueError(f"Rite '{action}' requires 'to_number'.")
            if not self.body and not self.media_url:
                raise ValueError(f"Rite '{action}' requires 'body' or 'media_url'.")

        # Provisioning Validation
        if action == 'buy':
            if not self.phone_number:
                raise ValueError(f"Rite '{action}' requires 'phone_number'.")

        # Search Validation
        if action == 'search':
            if not self.country_code:
                # Default applied in field, but safety check
                raise ValueError("Rite 'search' requires 'country_code'.")

        return self


class TwilioA2PRequest(BaseRequest):
    """[THE REGULATORY PLEA] Command Twilio to execute Trust Hub rites."""
    action: str = Field(..., pattern=r"^(create_brand|create_campaign|link_number|check_status)$")

    # Brand Matter
    legal_name: Optional[str] = None
    tax_id: Optional[str] = None  # EIN/Registration Number
    website: Optional[str] = None

    # Campaign Matter
    use_case: str = Field("CUSTOMER_CARE", description="A2P Use Case code.")
    description: str = Field(..., description="Nature of the messaging.")
    sample_msgs: List[str] = Field(default_factory=list)

    # Binding Matter
    messaging_service_sid: Optional[str] = None
    phone_number_sid: Optional[str] = None


def get_default_signup_url():
    """Dynamically determines the canonical sign-up path based on environment."""
    # Priority: Env variable > Custom Domain > Default Path
    domain = os.environ.get("NEXT_PUBLIC_BASE_DOMAIN", "https://novalym.com")
    # Ensure it uses the explicit sign-up path
    return f"{domain}/sign-up"


class ClerkRequest(BaseRequest):
    """
    =============================================================================
    == THE IDENTITY VESSEL (V-Ω-CLERK-ULTIMA-V2)                               ==
    =============================================================================
    LIF: ∞ | ROLE: IDENTITY_GOVERNOR | RANK: LEGENDARY

    The definitive contract for all interactions with the Clerk.com API,
    optimized for self-service sign-up flows.
    """
    model_config = ConfigDict(extra='ignore', populate_by_name=True)

    # --- THE RITE OF ACTION ---
    action: Literal[
        "invite", "revoke_invite", "list_invites",  # Invitations
        "get_user", "update_user", "delete_user", "list_users",  # Users
        "get_org", "create_org", "update_org", "add_member",  # Organizations
        "update_metadata", "get_sessions", "kick_session"  # Meta & Governance
    ] = Field(..., description="The Auth Rite to conduct.")

    # --- COORDINATES ---
    email: Optional[str] = Field(None, description="The primary soul anchor.")
    user_id: Optional[str] = Field(None, description="Clerk User ID (user_...).")
    org_id: Optional[str] = Field(None, description="Clerk Org ID (org_...).")
    invitation_id: Optional[str] = Field(None, description="Invite ID (inv_...).")
    session_id: Optional[str] = Field(None, description="Session ID (sess_...).")

    # --- THE GNOSTIC PAYLOAD ---
    public_metadata: Optional[Dict[str, Any]] = Field(None, description="Visible to the frontend UI.")
    private_metadata: Optional[Dict[str, Any]] = Field(None, description="Visible only to the Python Brain.")
    unsafe_metadata: Optional[Dict[str, Any]] = Field(None, description="Mutable by the user (rarely used).")

    # --- PARAMETERS ---
    first_name: Optional[str] = None
    last_name: Optional[str] = None
    role: Optional[str] = Field("basic_member", description="Org role (admin/member).")

    # [THE CURE]: DYNAMIC SIGN-UP ANCHOR
    # The default is now the initial sign-up portal, ensuring the token is processed.
    # We make it Optional, and the default is defined by the function above.
    redirect_url: Optional[str] = Field(
        default_factory=get_default_signup_url,
        description="URL to redirect user to after an action (e.g., setting password)."
    )

    limit: int = Field(10, ge=1, le=100)
    offset: int = Field(0, ge=0)

    # --- SIMULATION ---
    simulation: bool = Field(False, description="Force Phantom Circuit even in Prod.")


# =============================================================================
# == THE TEMPORAL RITE TAXONOMY                                              ==
# =============================================================================

class TemporalAction(str, Enum):
    SCRY_SLOTS = "scry_slots"
    BOOK_CONFIRM = "book_confirm"
    CANCEL_EVENT = "cancel_event"
    SYNC_CHECK = "sync_check"
    VERIFY_STATUS = "verify_status"
    RESCHEDULE = "reschedule"
class TemporalProvider(str, Enum):
    CAL_COM = "cal.com"
    GOOGLE = "google"
    OUTLOOK = "outlook"
    CALENDLY = "calendly"
    CUSTOM = "custom"

# =============================================================================
# == THE TEMPORAL TARGET (V-Ω-SOVEREIGN_COORDINATE)                          ==
# =============================================================================
# =============================================================================
# == THE TEMPORAL TARGET (V-Ω-SOVEREIGN_COORDINATE)                          ==
# =============================================================================
class CalendarTarget(BaseModel):
    """
    [THE GNOSTIC COORDINATE]
    The immutable DNA of the target calendar reality (The Client's Config).
    """
    model_config = ConfigDict(extra='ignore', frozen=True)

    # --- PRIMARY IDENTITY ANCHORS (Pulled from Client's JSONB) ---
    username: str = Field(..., description="The user's unique Cal.com namespace.")
    event_type_id: Union[int, str] = Field(..., description="The specific event/meeting type slug or ID.")

    # --- KINETIC KEYS (Override Fuel - Defaults to Master Key) ---
    api_key: Optional[str] = Field(None, description="A tenant-specific Cal.com API key, if overriding Master.")

    # --- PHYSICS & BEHAVIOR ---
    timezone: str = Field("UTC", description="The target timezone for displaying slots.")
    buffer_mins: int = Field(60, ge=0, description="The 'Biological Cooldown' - Safety minutes between calls.")


# =============================================================================
# == THE CALENDAR REQUEST (V-Ω-ULTIMA_TOTALITY_FINALIS_V3)                   ==
# =============================================================================
class CalendarRequest(BaseRequest):
    """
    =============================================================================
    == THE CALENDAR REQUEST (V-Ω-ULTIMA_TOTALITY_FINALIS_V3)                   ==
    =============================================================================
    LIF: ∞ | ROLE: SPACETIME_COORDINATE_PLEA | RANK: SOVEREIGN

    The final, definitive, and unbreakable Gnostic Contract for all temporal movements.
    It is the centralized source of truth for the entire Scaffold Monolith.
    """
    model_config = ConfigDict(
        extra='ignore',
        frozen=True,
        populate_by_name=True,
        arbitrary_types_allowed=True
    )

    # --- 1. THE SACRED ACTION ---
    action: TemporalAction = Field(..., description="The specific temporal movement to conduct.")
    provider: TemporalProvider = Field(default=TemporalProvider.CAL_COM, description="The celestial scheduling engine.")

    # --- 2. THE TARGET REALITY (CRITICAL SUTURE) ---
    # This carries all the client's config data for the Artisan to use.
    target: CalendarTarget = Field(..., description="The immutable configuration and identity of the target calendar.")

    # --- 3. THE LEAD'S BIOMETRIC SOUL (For Booking) ---
    novalym_id: str = Field(..., description="The Sovereign ID of the Client Entity.")
    lead_phone: str = Field(..., description="The E.164 coordinate of the Lead.")
    lead_name: Optional[str] = Field("Valued Client", description="The humanized name for the invite.")
    lead_email: Optional[EmailStr] = Field(None, description="The digital soul coordinate for the invite.")

    # --- 4. THE CONVERSATIONAL STATE (For Multi-Turn Booking) ---
    selected_option: Optional[Literal["A", "B", "C"]] = Field(None,
                                                              description="The A/B/C slot identifier chosen by the lead.")
    explicit_timestamp: Optional[str] = Field(None, description="A direct ISO8601 string for booking.")

    # --- 5. PHYSICS & OVERRIDES ---
    duration_mins: int = Field(default=15, ge=5, description="The mass of the meeting in time.")
    force: bool = Field(default=False, description="Bypass safety checks and cache.")

    # --- 6. METADATA & FORENSICS ---
    metadata: Dict[str, Any] = Field(default_factory=dict,
                                     description="Forensic metadata (trace_id, simulation, ui_hints).")

    # =========================================================================
    # == COMPUTED REALITIES (ASCENSION 6 & 5 & 3)                            ==
    # =========================================================================

    @computed_field
    @property
    def is_simulation(self) -> bool:
        """Adjudicates reality mode from multiple sources."""
        if self.metadata.get("simulation") is not None:
            return bool(self.metadata["simulation"])
        return os.environ.get("SCAFFOLD_ENV") == "development"

    @computed_field
    @property
    def merkle_id(self) -> str:
        """[ASCENSION 3]: Collision avoidance fingerprint."""
        raw = f"{self.novalym_id}:{self.lead_phone}:{self.action}"
        return hashlib.sha256(raw.encode()).hexdigest()[:12]

    # =========================================================================
    # == THE ALCHEMICAL VALIDATORS (ASCENSION 24 & 4)                        ==
    # =========================================================================

    @field_validator('lead_phone', mode='before')
    @classmethod
    def purify_phone(cls, v: Any) -> str:
        """The Telephonic Healer (E.164 Enforcer)."""
        if not v: return ""
        clean = "".join(c for c in str(v) if c.isdigit() or c == '+')
        if not clean.startswith('+'):
            if len(clean) == 10: return f"+1{clean}"
            return f"+{clean}"
        return clean

    @model_validator(mode="after")
    def verify_rite_viability(self) -> 'CalendarRequest':
        """FINALITY VOW - Logic Gates."""
        if self.action == TemporalAction.BOOK_CONFIRM and not (self.selected_option or self.explicit_timestamp):
            if not self.is_simulation:
                raise ValueError("The 'book_confirm' rite requires a selection.")
        return self

# == SCRIPTURE SEALED: THE CALENDAR CONTRACT REACHES TOTALITY ==
