# ============================================================
# src/accountable_record/stage_090_docs/index.py
# ============================================================
"""Plan, reconcile, and render stage 090 documentation (orchestration op).

WHY:
    index.py is the op the validation layer drives, mirroring the index op of
    stage 060. It composes the planning, reconciliation, and rendering ops over
    the stage 080 generated registry and returns their results together so the
    validation layer can emit AR.DC.* diagnostics and fold a DocsArtifact into
    state. It stays free of diagnostics and writes nothing.

OBS (consume the generated registry):
    The generated element set is passed in by the validation layer (from
    state.generated). This op does not rebuild the generated set or re-walk
    data/generated/.

OBS (no writes):
    Read-only with respect to the filesystem. Plans, reconciles, and renders in
    memory; writes nothing.
"""

from dataclasses import dataclass

from accountable_record.stage_080_generated.model import GeneratedRegistry
from accountable_record.stage_090_docs.model import (
    DocsReconciliation,
    DocsRenderPlan,
    RenderedPage,
)
from accountable_record.stage_090_docs.plan import (
    plan_documentation,
    reconcile_plan_with_generated,
)
from accountable_record.stage_090_docs.render import render_pages

__all__ = ["DocsBuild", "build_documentation"]


@dataclass(frozen=True)
class DocsBuild:
    """The planned, reconciled, and rendered documentation for one run.

    Attributes:
        plan: The documentation render plan.
        reconciliation: The plan-vs-generated reconciliation result.
        rendered: The in-memory rendered pages.
    """

    plan: DocsRenderPlan
    reconciliation: DocsReconciliation
    rendered: tuple[RenderedPage, ...]


def build_documentation(registry: GeneratedRegistry) -> DocsBuild:
    """Plan, reconcile, and render documentation for the generated registry.

    Args:
        registry: The stage 080 generated element registry.

    Returns:
        A DocsBuild carrying the plan, the reconciliation against the generated
        set, and the in-memory rendered pages.
    """
    plan = plan_documentation(registry)
    reconciliation = reconcile_plan_with_generated(plan, registry)
    rendered = render_pages(plan)

    return DocsBuild(
        plan=plan,
        reconciliation=reconciliation,
        rendered=rendered,
    )
