"""Phase 2 — Reason: accept gathered context, produce reasoning output.

This is the deliberation phase. It receives enriched context from Phase 1
and decides what to do. In the stub form, it passes the payload through
with a phase marker.
"""

from __future__ import annotations

import logging

from loop.schema import ContextPayload

logger = logging.getLogger(__name__)


def reason(payload: ContextPayload) -> ContextPayload:
    """Accept gathered context and return a reasoning result.

    Stub: tags the payload with phase=reason and logs transit.
    Timmy will flesh this out with LLM calls, confidence scoring,
    plan generation, and judgment logic.
    """
    logger.info(
        "Phase 2 (Reason) received: source=%s gathered=%s",
        payload.source,
        payload.metadata.get("gathered", False),
    )

    result = payload.with_metadata(phase="reason", reasoned=True)

    logger.info(
        "Phase 2 (Reason) produced: metadata_keys=%s",
        sorted(result.metadata.keys()),
    )
    return result