// Answer-grounding policy decision (Epic #189, Issue #199). Pure function over the
// retrieval result + the capsule's configured `answerGroundingPolicy`. Lives at the
// boundary between retrieval and the future #200 Conversation Center integration: the
// runner uses it to decide whether to release retrieved evidence to the LLM grounding
// prompt, and the UI layer reads `noEvidence` / `reason` to phrase the user-visible
// message.
//
// Three policies (matching `CapsuleAnswerGroundingPolicy` in contracts):
//   * "require-citations" — empty refs MUST block; no answer can fire.
//   * "require-citations-or-state-no-evidence" — empty refs are allowed *if* the caller
//     surfaces a "no evidence" message; the decision marks `noEvidence: true` so the
//     caller knows it has to.
//   * "best-effort" — empty refs are allowed; the LLM may answer without citations.
//
// `validateAnswerGrounding` is deliberately a *function*, not a method on a capsule or a
// store call. No IO, no allocation beyond the returned record. Tests pin every branch.
export function validateAnswerGrounding(references, policy) {
    const hasReferences = references.length > 0;
    if (policy === "require-citations") {
        if (hasReferences)
            return { allow: true, reason: "allowed", noEvidence: false };
        return { allow: false, reason: "require-citations-rejected", noEvidence: true };
    }
    if (policy === "require-citations-or-state-no-evidence") {
        if (hasReferences)
            return { allow: true, reason: "allowed", noEvidence: false };
        return { allow: true, reason: "no-evidence-stated", noEvidence: true };
    }
    // best-effort
    return { allow: true, reason: "allowed", noEvidence: !hasReferences };
}
