"""
topology.py — The Topology Engine of the Modular Reasoning Scaffold (MRS).

This file defines the core transition operator 𝒯, which governs how reasoning
steps update, branch, or halt. In contrast to RecursionNode, which is passive,
TopologyEngine contains the decision logic.

The engine is intentionally simple: deterministic, explainable transitions.
"""

from typing import Any, Dict, Callable
from .core import RecursionNode, StateTracker, ConstraintMonitor


class TopologyEngine:
    """
    Determines reasoning flow for MRS.

    The topology engine is responsible for:
    - deciding the next input to the model
    - branching conditions
    - reflective transitions
    - halting conditions

    Parameters
    ----------
    policy : Callable
        A user-provided function implementing R_{i+1} = T(R_i, S_i, C_i).

    Methods
    -------
    next_step(node, state, constraints):
        Compute and return the next recursion directive.
    """

    def __init__(self, policy: Callable):
        self.policy = policy

    def next_step(
        self,
        node: RecursionNode,
        state: StateTracker,
        constraints: ConstraintMonitor
    ) -> Dict[str, Any]:
        """
        Compute topology transition.

        Parameters
        ----------
        node : RecursionNode
            The current reasoning step.
        state : StateTracker
            The full history of prior outputs.
        constraints : ConstraintMonitor
            Drift-based stability monitor.

        Returns
        -------
        Dict[str, Any]
            Instruction dictionary describing the next recursion input,
            transformation rule, or halt signal.

        Notes
        -----
        The returned instruction is intentionally flexible, allowing custom 
        scaffolds such as:
        - forward recursive expansion
        - multi-branch tree-of-thought
        - reflective consolidation phases
        - forced halting on constraint violation
        """
        return self.policy(node, state, constraints)
