"""musehub#225 — service.py's docstring falsely claimed to be "the unified
surface enforcing all three invariants atomically." It has zero production
callers; the actual enforcement surface is push_validator.py (musehub#230).

Resolution (confirmed via check-in): IdentityGraphService/QuorumEngine are
NOT dead code to delete -- docs/roadmaps/orgs.md (actively maintained, not
a stale artifact) documents them as built-ahead infrastructure for a
deliberately-deferred "sub-org nesting" feature ("the QuorumEngine
supports it; the CLI does not need to expose it yet"). The fix is
docstring-only: stop claiming current enforcement, accurately describe
them as reserved/unwired infrastructure for that documented future
capability.
"""
from __future__ import annotations

import re


def _claims_enforcement(doc: str) -> bool:
    """True if *doc* asserts this module currently enforces/is the
    enforcement surface for identity invariants -- as opposed to describing
    itself as reserved, unwired, or future infrastructure."""
    return bool(re.search(r"unified surface enforcing", doc, re.IGNORECASE))


def test_service_module_docstring_no_longer_claims_current_enforcement() -> None:
    from musehub.graph import service

    doc = service.__doc__ or ""
    assert not _claims_enforcement(doc), (
        f"service.py's docstring must not claim to be a currently-enforcing "
        f"surface -- IdentityGraphService has zero production callers "
        f"(musehub#225). Got: {doc!r}"
    )


def test_service_module_docstring_references_roadmap_and_deferred_status() -> None:
    from musehub.graph import service

    doc = service.__doc__ or ""
    assert "orgs.md" in doc or "roadmap" in doc.lower(), (
        "service.py's docstring should cross-reference docs/roadmaps/orgs.md "
        "so a future reader understands this is intentionally-deferred "
        "infrastructure, not orphaned code"
    )
    assert "225" in doc, "service.py's docstring should cross-reference musehub#225"


def test_quorum_module_docstring_references_roadmap_and_deferred_status() -> None:
    from musehub.graph import quorum

    doc = quorum.__doc__ or ""
    assert "orgs.md" in doc or "roadmap" in doc.lower(), (
        "quorum.py's docstring should cross-reference docs/roadmaps/orgs.md "
        "now that musehub#225 has resolved whether this code is kept"
    )
    assert "225" in doc, "quorum.py's docstring should cross-reference musehub#225"
    # musehub#225 resolved the open question quorum.py's own docstring posed --
    # it must no longer read as an unresolved question.
    assert "musehub#225's decision" not in doc


def test_graph_package_docstring_does_not_overclaim_quorum() -> None:
    """The package docstring listed "quorum soundness" as a current offering
    of the graph package -- misleading now that it's documented as deferred,
    unwired infrastructure rather than an active capability."""
    import musehub.graph as graph_pkg

    doc = graph_pkg.__doc__ or ""
    assert "quorum soundness" not in doc.lower()