/**
 * An inert, machine-independent descriptor of one planned trial. Mirrors the
 * fields of a `TrialWorkItem` that a strategy may reason about, minus the live
 * `execute()` closure. `shardKey` is the stable identity a strategy returns to
 * claim the trial.
 */
export interface ShardableItem {
    /** Stable shard key (from {@link computeShardKey}). */
    shardKey: string;
    /** Variant name. */
    variant: string;
    /** Eval file path relative to the experiment directory. */
    evalFile: string;
    /** Effective model, or `undefined` for the eval's configured default. */
    model?: string;
    /** Resolved stimulus name. */
    stimulus: string;
    /** 0-based trial index. */
    trialIndex: number;
    /** Total trials for the stimulus. Always >= 1. */
    totalTrials: number;
}
/** Context passed to {@link ShardStrategy.select}. */
export interface ShardSelectContext {
    /** Every planned trial in the run, as inert descriptors. The runner passes
     *  these sorted by `shardKey`, but a strategy must not rely on input order —
     *  it should sort by whatever key it needs. */
    items: readonly ShardableItem[];
    /** This shard's identity. */
    shard: {
        /** 1-based shard index. */
        index: number;
        /** Total shard count. */
        total: number;
    };
}
/**
 * Strategy that partitions a planned run across shards. `select` returns the
 * shard keys THIS shard should run. Across all `total` shards the union of
 * returned keys should cover the planned set exactly once (the built-ins
 * guarantee this); the runtime only validates each shard's own return is a
 * clean subset (merge enforces the global partition).
 */
export interface ShardStrategy {
    /** Stable strategy name, recorded in the shard manifest. */
    name: string;
    /** Pick the shard keys for `ctx.shard`. Must be synchronous and return a
     *  plain array of shard-key strings drawn from `ctx.items`. */
    select(ctx: ShardSelectContext): string[];
}
/** Names that resolve to a built-in strategy without module loading. */
export declare const BUILT_IN_SHARD_STRATEGIES: readonly ["round-robin", "by-stimulus"];
/** Default strategy specifier when `--shard-strategy` is omitted. */
export declare const DEFAULT_SHARD_STRATEGY = "round-robin";
/**
 * Round-robin over individual trials: sort items by `shardKey`, then assign
 * sorted item `i` to shard `i % total`. Even distribution; does not keep a
 * stimulus's trials together.
 */
export declare const roundRobinStrategy: ShardStrategy;
/**
 * Round-robin over stimulus groups: every trial of one stimulus is assigned to
 * the same shard. Sort groups by their `(evalFile, variant, model, stimulus)`
 * tuple, then assign group `g` to shard `g % total`. Keeps per-stimulus
 * multi-trial scoring contexts intact within a single shard.
 */
export declare const byStimulusStrategy: ShardStrategy;
/**
 * Resolve a `--shard-strategy` specifier to a {@link ShardStrategy}.
 *
 * Built-in names (`round-robin`, `by-stimulus`) short-circuit before any module
 * resolution. Otherwise the specifier is treated as a module — an npm package
 * name or a local file path — resolved from `cwd` via the shared plugin
 * specifier resolver, dynamically imported, and expected to export a
 * `createShardStrategy(): ShardStrategy` factory. Custom strategy code is
 * TRUSTED (full Node privileges, no sandbox).
 */
export declare function resolveShardStrategy(specifier: string, options?: {
    cwd?: string;
}): Promise<{
    strategy: ShardStrategy;
    specifier: string;
}>;
/**
 * Validate the shard keys a strategy returned for one shard against the planned
 * set. Enforces only the per-shard contract: the return must be a plain array
 * of strings, contain no duplicates, and every key must be a planned key. An
 * empty selection is legal (a shard can be empty when `total` exceeds the trial
 * count). Cross-shard exhaustiveness / non-overlap is NOT checked here — that is
 * merge's job. Returns the selected keys sorted.
 */
export declare function validateSelectedShardKeys(selected: unknown, plannedKeys: Iterable<string>, shard: {
    index: number;
    total: number;
}, strategyName: string): string[];
//# sourceMappingURL=shard-strategy.d.ts.map