/**
 * Shared schema and normalizer for `engine.aggregate()` options — the
 * `groupBy` dimension and the optional `limit` on returned groups. Lives
 * in `core/` so in-process callers and the server operation share one
 * validation path.
 *
 * The list-filter portion of aggregate input is validated by
 * {@link normalizeListFilter} in `list-filter-validation.ts`; this module
 * covers only the aggregate-specific options.
 *
 * @module core/aggregate-validation
 */
import { z } from 'zod';
import { type ValidationIssue } from './validation-issues.ts';
import { WeftError } from './weft-error.ts';
/**
 * Group-by dimension for `engine.aggregate()`. Either a fixed structural
 * dimension or an arbitrary search-attribute name.
 */
export type AggregateGroupBy = 'status' | 'type' | 'failureCategory' | {
    attribute: string;
};
/**
 * Validated options for `engine.aggregate()`. `limit` bounds the number
 * of groups returned; `undefined` means "use the engine default."
 */
export type AggregateOptions = {
    groupBy: AggregateGroupBy;
    limit?: number;
};
/**
 * Default and maximum bounds on the number of groups returned. Groups
 * over the requested limit set `truncated: true` on the response.
 */
export declare const AGGREGATE_DEFAULT_LIMIT = 1000;
export declare const AGGREGATE_MAX_LIMIT = 10000;
/**
 * Hard cap on the number of distinct group keys the engine will
 * materialize for a single aggregate query. Exceeding it raises
 * {@link AggregateDistinctKeyCapExceededError}; transport layers map
 * the error to `Unprocessable`. The cap protects against an unbounded
 * group-by on a high-cardinality attribute exhausting memory; it is
 * never silently truncated because scan-order would bias which groups
 * "win."
 */
export declare const MAX_AGGREGATE_DISTINCT_KEYS = 100000;
/**
 * Concrete object schema for {@link AggregateOptions}. Exported so the
 * server operation can `.extend()` it onto the list-filter schema.
 */
export declare const aggregateOptionsObjectSchema: z.ZodObject<{
    groupBy: z.ZodUnion<readonly [z.ZodLiteral<"status">, z.ZodLiteral<"type">, z.ZodLiteral<"failureCategory">, z.ZodObject<{
        attribute: z.ZodString;
    }, z.core.$strict>]>;
    limit: z.ZodOptional<z.ZodNumber>;
}, z.core.$strict>;
/** A flattened Zod issue suitable for cross-transport serialization. */
export type AggregateOptionsValidationIssue = ValidationIssue;
/**
 * Thrown by {@link normalizeAggregateOptions} when input fails validation.
 * Carries flattened Zod issues so transport adapters can map directly to
 * the existing `InvalidParams` fault shape.
 */
export declare class AggregateOptionsValidationError extends WeftError<'AggregateOptionsValidationError'> {
    readonly issues: ReadonlyArray<AggregateOptionsValidationIssue>;
    constructor(issues: ReadonlyArray<AggregateOptionsValidationIssue>);
}
/**
 * Thrown when an aggregate query would materialize more distinct group
 * keys than {@link MAX_AGGREGATE_DISTINCT_KEYS}. Caller is expected to
 * narrow the filter or pick a lower-cardinality `groupBy`.
 */
export declare class AggregateDistinctKeyCapExceededError extends WeftError<'AggregateDistinctKeyCapExceededError'> {
    readonly cap: number;
    constructor(cap: number);
}
/**
 * Parse and validate aggregate options. Returns a typed copy on success;
 * throws {@link AggregateOptionsValidationError} on failure with
 * structured issues.
 */
export declare function normalizeAggregateOptions(input: unknown): AggregateOptions;