"""Phase 1 — Gather: accept raw input, produce structured context.

This is the sensory phase. It receives a raw ContextPayload and enriches
it with whatever context Timmy needs before reasoning. In the stub form,
it simply passes the payload through with a phase marker.
"""

from __future__ import annotations

import logging

from loop.schema import ContextPayload

logger = logging.getLogger(__name__)


def gather(payload: ContextPayload) -> ContextPayload:
    """Accept raw input and return structured context for reasoning.

    Stub: tags the payload with phase=gather and logs transit.
    Timmy will flesh this out with context selection, memory lookup,
    adapter polling, and attention-residual weighting.
    """
    logger.info(
        "Phase 1 (Gather) received: source=%s content_len=%d tokens=%d",
        payload.source,
        len(payload.content),
        payload.token_count,
    )

    result = payload.with_metadata(phase="gather", gathered=True)

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