/**
 * `engine.aggregate()` — group-by counts over a {@link ListFilter}.
 * Shares the candidate-resolution path with `engine.list()` so the
 * watermark gate, scan cap, and indexed narrowing behave identically.
 *
 * @module core/engine/aggregate
 */
import { type AggregateGroupBy, type AggregateOptions } from '../aggregate-validation.ts';
import type { ListFilter } from '../types.ts';
import { WeftError } from '../weft-error.ts';
import type { EngineInternals } from './internals.ts';
/** One group in an {@link AggregateResult}. `key === null` collects workflows missing the dimension. */
export type AggregateGroup = {
    key: string | null;
    count: number;
};
/**
 * Result of `engine.aggregate()`. `total` is the count of candidates that
 * passed filtering; `groups` is sorted by `count desc, key asc` and
 * truncated to the caller's `limit`. `truncated` is `true` when there
 * were more groups than `limit` allowed.
 */
export type AggregateResult = {
    total: number;
    groups: AggregateGroup[];
    truncated: boolean;
};
type AggregateExecutionOptions = {
    distinctKeyCap?: number;
};
/**
 * Thrown when an aggregate `groupBy: { attribute }` references a search
 * attribute that no registration declares. Maps to an `Unprocessable`
 * fault at the operation boundary.
 */
export declare class UnknownAggregateAttributeError extends WeftError<'UnknownAggregateAttributeError'> {
    readonly attribute: string;
    constructor(attribute: string);
}
/**
 * Aggregate workflows by a single dimension. The filter shape matches
 * `engine.list()`; `limit` and `offset` on the filter are ignored
 * (aggregation always considers every candidate that passes the rest of
 * the filter). The aggregate `limit` bounds the returned groups instead.
 */
export declare function aggregate(internals: EngineInternals, filter: ListFilter | undefined, options: AggregateOptions, executionOptions?: AggregateExecutionOptions): Promise<AggregateResult>;
export type { AggregateGroupBy, AggregateOptions };