/** Bounded deterministic selection/grouping helpers for public read views. */
import type { CoverageFacet, GraphReadFacetCoverage } from './query-contracts.js';
/** One group key and its match count for a bounded grouped read view. */
export interface ReadGroupSummary {
    readonly key: string;
    readonly count: number;
}
/**
 * Clamp a caller-supplied limit to a positive integer in [1, 500], defaulting
 * when absent or non-finite. The read surface is self-defending: a malformed
 * `limit` (NaN/Infinity) must coerce to `fallback` here, never propagate into
 * `Math.min`/`Math.max` (whose NaN result silently yields an empty window
 * labeled `complete: true`). Canonical home for both the graph read views and
 * the MCP query pre-clamps (consolidated from `mcp/graph-read-projection`).
 */
export declare function clampLimit(limit: number | undefined, fallback: number): number;
/**
 * The one truncation classifier for read-coverage reasons: registered cap
 * codes (declared cap-ness) plus the `-cap` suffix convention as
 * defense-in-depth. Every consumer (`makeFacet`, symbol search) routes
 * through this — no per-site suffix sniffing.
 */
export declare function isCapReason(code: string): boolean;
/** A facet the caller did not request — complete, untruncated, contributes nothing. */
export declare const UNREQUESTED_FACET: CoverageFacet;
/**
 * Build one {@link CoverageFacet} from its requested flag + accumulated reasons.
 * `-cap` reasons mark truncation; any reason marks incompleteness. Reasons are
 * deduplicated and code-point sorted for deterministic output.
 */
export declare function makeFacet(requested: boolean, reasons: ReadonlySet<string>): CoverageFacet;
/**
 * Merge two facets of the SAME name (e.g. a view's evidence facet with the MCP
 * pager's projection facet): requested if either is, complete only if both are,
 * truncated if either is, reasons unioned + sorted.
 */
export declare function mergeFacet(a: CoverageFacet, b: CoverageFacet): CoverageFacet;
/** The four facets that compose a graph read's coverage. */
export interface CoverageFacetSet {
    readonly inventory: CoverageFacet;
    readonly evidence: CoverageFacet;
    readonly grouping: CoverageFacet;
    readonly projection: CoverageFacet;
}
/**
 * Roll a {@link CoverageFacetSet} into full {@link GraphReadFacetCoverage}. The
 * top-level summary aggregates ONLY the requested facets: complete when every
 * requested facet is complete, truncated when any requested facet is, reasons
 * unioned across requested facets. An unrequested facet never leaks into it.
 */
export declare function rollupFacets(facets: CoverageFacetSet): GraphReadFacetCoverage;
/** Insert into an ascending top-K window without retaining rejected rows. */
export declare function insertBoundedTopK<T>(window: T[], row: T, cap: number, compare: (a: T, b: T) => number): void;
/** Insert into an ascending top-K window while collapsing comparator-equal rows. */
export declare function insertUniqueBoundedTopK<T>(window: T[], row: T, cap: number, compare: (a: T, b: T) => number): void;
/**
 * Deterministically retain the lowest `maxGroups` keys, then count them in a
 * second pass. Memory is O(maxGroups), even when the filtered row set is large.
 */
export declare function boundedGroups<T>(rows: readonly T[], keyOf: (row: T) => string, maxGroups?: number): {
    groups: readonly ReadGroupSummary[];
    truncated: boolean;
};
/** Two-pass bounded grouping for a repeatable iterable factory. */
export declare function boundedIterableGroups<T>(rows: () => Iterable<T>, keyOf: (row: T) => string, maxGroups?: number): {
    groups: readonly ReadGroupSummary[];
    truncated: boolean;
};
//# sourceMappingURL=bounded-view.d.ts.map