import { RecallDisclosure } from './types.js';

/**
 * Recall disclosure auto-escalation policy (issue #677 PR 4/4).
 *
 * Pure helper that decides the *effective* disclosure depth for a recall
 * given the configured policy and the observed top-K confidence.  Lives
 * outside `access-service.ts` so the decision logic can be unit-tested
 * exhaustively without booting an orchestrator.
 *
 * Policy summary:
 *
 *   manual (default):
 *     The caller's `disclosure` is honored verbatim.  Auto-escalation
 *     does not run.
 *
 *   auto:
 *     If the caller did NOT explicitly specify a disclosure (i.e. the
 *     value in use is the system default) AND the recall's top-K
 *     confidence falls below the configured threshold, escalate from
 *     `chunk` to `section`.  `raw` is never auto-selected — it requires
 *     an explicit caller request because of its higher cost and the
 *     LCM-archive read paths it activates.  If the caller explicitly
 *     passed a disclosure (even `chunk`), the policy respects that
 *     choice and does not escalate.
 *
 * The threshold compares against `final` from the top result's score
 * decomposition.  When the snapshot has no results or no scores, no
 * escalation fires (`undefined` confidence is treated as "skip" rather
 * than "always escalate").
 */

type DisclosureEscalationMode = "manual" | "auto";
declare const DISCLOSURE_ESCALATION_MODES: readonly DisclosureEscalationMode[];
declare function isDisclosureEscalationMode(value: unknown): value is DisclosureEscalationMode;
/**
 * Threshold defaults — applied when config-side coercion produces an
 * out-of-range or missing value.  0.5 is a deliberate midpoint:
 * confidently-served recalls (top-K >= 0.5) stay on the cheap chunk
 * tier; ambiguous recalls escalate to section.
 */
declare const DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD = 0.5;
interface DisclosureEscalationDecision {
    /** The disclosure depth the caller should use to shape the response. */
    effective: RecallDisclosure;
    /**
     * `true` when the policy escalated from the original disclosure;
     * `false` when the original was kept (either by manual mode, by
     * caller explicit choice, or because confidence stayed above the
     * threshold).
     */
    escalated: boolean;
    /**
     * Human-readable reason for the decision.  Always populated; surfaces
     * in operator-facing telemetry / debug paths.
     */
    reason: string;
}
interface DecideDisclosureEscalationInput {
    /** The mode from config (`manual` | `auto`). */
    mode: DisclosureEscalationMode;
    /** Threshold in [0, 1]; values outside this range fall back to the default. */
    threshold: number;
    /** Disclosure resolved at request time (after default-fill). */
    originalDisclosure: RecallDisclosure;
    /**
     * Whether the caller explicitly specified a disclosure value.  Auto
     * mode only acts when the caller did NOT specify, so explicit
     * `chunk` requests are not silently upgraded.
     */
    callerProvidedDisclosure: boolean;
    /**
     * Top-K confidence (`final` score from the highest-ranked result),
     * or `undefined` when the snapshot has no scored results.
     */
    topKConfidence: number | undefined;
}
/**
 * Decide whether to escalate disclosure depth based on policy + signals.
 * Pure function — no IO, no state.
 */
declare function decideDisclosureEscalation(input: DecideDisclosureEscalationInput): DisclosureEscalationDecision;

export { DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD, DISCLOSURE_ESCALATION_MODES, type DecideDisclosureEscalationInput, type DisclosureEscalationDecision, type DisclosureEscalationMode, decideDisclosureEscalation, isDisclosureEscalationMode };
