"""Broad-quantifier reminder text — Ticket #000008 Phase 3.

Default-OFF mechanism. Lands the wiring + the reminder strings; a
operator flips ``quantifier_reminder_enabled=True`` on a per-call
basis to opt in. Bench-first per §10.8 decision tree: enable
default-on only when reminder injection moves FORMAT_COLLAPSED rate
or pointer-loss rate by ≥5pp on the broad-quantifier subset of the
bench.

The reminder is one user-turn message appended AFTER the standard
grounding reminder and BEFORE the evidence-map + question payload —
landing in the same position the existing reminder already uses.
Empirical justification for that placement: Hermes-3-8B attention
weights the most-recent tokens heavily, so the reminder right
before the payload survives enumeration pressure better than a
buried system-prompt clause.

Two reminder shapes:

  - bounded universe ("all members of the Beatles", year-anchored)
      "This is a broad-quantifier query with a bounded universe.
       Return at most N pointer-linked claim lines."
  - unbounded universe ("winners of all major sports")
      "This is a broad-quantifier query with an under-specified
       scope. Return at most N pointer-linked claim lines. If you
       cannot ground N claims with evidence IDs, return fewer
       grounded claims. Do not enumerate from training prior."

Returns ``None`` for non-broad intensities — caller skips the
append in that case.
"""

from __future__ import annotations


_BOUNDED_TEMPLATE = (
    "This is a broad-quantifier query with a bounded universe. "
    "Return at most {cap} pointer-linked claim lines. Each claim "
    "must cite an evidence id like [E5]; do not write claim lines "
    "without bracket citations."
)

_UNBOUNDED_TEMPLATE = (
    "This is a broad-quantifier query with an under-specified "
    "scope. Return at most {cap} pointer-linked claim lines. If "
    "you cannot ground {cap} claims with evidence IDs, return "
    "fewer grounded claims. Do not enumerate from training prior. "
    "Each claim must cite an evidence id like [E5]; do not write "
    "claim lines without bracket citations."
)


def broad_quantifier_reminder(
    *,
    intensity: str | None,
    cap: int | None,
    scope_bound_hint: str | None,
) -> str | None:
    """Return reminder text for a broad-quantifier query, or None.

    Caller is responsible for the gates (quantifier_guard_enabled,
    quantifier_mode_gated, quantifier_reminder_enabled). This
    function only formats the text once those gates have passed.

    None semantics:
      - intensity not in {ALL, COMPREHENSIVE, OPEN_REQUEST}
      - cap is None or non-positive (defensive — would render an
        ill-formed "at most None" message)
    """
    if intensity not in {"ALL", "COMPREHENSIVE", "OPEN_REQUEST"}:
        return None
    if cap is None or cap <= 0:
        return None
    if scope_bound_hint == "bounded":
        return _BOUNDED_TEMPLATE.format(cap=cap)
    return _UNBOUNDED_TEMPLATE.format(cap=cap)
