import type { SceneCandidatesArtifact, SceneSelectionArtifact } from './types.js';
/**
 * If the artifact already has an entry for `sceneIndex`, return the artifact
 * reference unchanged. Otherwise append a default (empty) entry.
 */
export declare function ensureSelectionEntry(artifact: SceneSelectionArtifact, sceneIndex: number): SceneSelectionArtifact;
/**
 * Sets the selected candidate id. Pulls the id out of `rejectedCandidateIds`
 * and `pendingCandidateIds` so the disjointness invariant holds, and clears
 * `rerollRequested` because a concrete pick supersedes an in-flight reroll.
 */
export declare function selectCandidate(artifact: SceneSelectionArtifact, sceneIndex: number, candidateId: string): SceneSelectionArtifact;
/**
 * Adds the candidate id to `rejectedCandidateIds` (dedup), removes it from
 * `pendingCandidateIds`, and clears `selectedCandidateId` if it matched.
 */
export declare function rejectCandidate(artifact: SceneSelectionArtifact, sceneIndex: number, candidateId: string): SceneSelectionArtifact;
/**
 * Adds the given candidate ids to `pendingCandidateIds`, skipping any that
 * already appear in `selectedCandidateId` or `rejectedCandidateIds` and any
 * that are already pending. Preserves existing order; appends new ids in the
 * order they were passed.
 */
export declare function markPending(artifact: SceneSelectionArtifact, sceneIndex: number, candidateIds: string[]): SceneSelectionArtifact;
/**
 * Marks the scene as needing a reroll. Clears `selectedCandidateId` so the
 * operator has to make a fresh pick once the reroll produces a new candidate.
 * When `chainFromPrev` is passed, sets the chain flag explicitly; otherwise
 * leaves it unchanged.
 */
export declare function requestReroll(artifact: SceneSelectionArtifact, sceneIndex: number, chainFromPrev?: boolean): SceneSelectionArtifact;
/**
 * Explicitly sets the `chainFromPrev` flag. Turning it OFF also clears any
 * explicit `chainFromSceneIndex` so an image-only rung leaves no stale source.
 */
export declare function setChainFromPrev(artifact: SceneSelectionArtifact, sceneIndex: number, value: boolean): SceneSelectionArtifact;
/**
 * Chain this scene from a SPECIFIC upstream scene (auto-chain fallback ladder).
 * Sets `chainFromPrev` true and pins `chainFromSceneIndex`; the chain seed then
 * resolves from that scene's selected candidate instead of `sceneIndex - 1`.
 */
export declare function setChainFromSource(artifact: SceneSelectionArtifact, sceneIndex: number, sourceSceneIndex: number): SceneSelectionArtifact;
/** Clears the `rerollRequested` flag. */
export declare function clearReroll(artifact: SceneSelectionArtifact, sceneIndex: number): SceneSelectionArtifact;
export interface SceneSelectionSummary {
    /** Number of scenes with at least one candidate. */
    sceneCount: number;
    /** Number of scenes where `selectedCandidateId` is set. */
    withSelection: number;
    /** Number of scenes with a non-empty `pendingCandidateIds[]`. */
    withPending: number;
    /** Number of scenes with `rerollRequested: true`. */
    withReroll: number;
    /** Total candidate count across all scenes. */
    totalCandidates: number;
    /** Sum of `rejectedCandidateIds[].length` across all scenes. */
    rejectedCount: number;
}
/**
 * Aggregates coverage counts across the candidates and selection artifacts.
 * Safe to call with the empty artifacts returned by the disk stores when the
 * underlying JSON file is missing, so this works on legacy projects that never
 * produced candidates.
 */
export declare function summarizeSceneSelection(candidates: SceneCandidatesArtifact, selection: SceneSelectionArtifact): SceneSelectionSummary;
export interface ValidationResult {
    ok: boolean;
    errors: string[];
}
/**
 * Validates a selection artifact against a candidates artifact.
 *
 * Checks:
 *  - `unknown-candidate-ref` — every id referenced by selection must exist in
 *    the candidates artifact.
 *  - `disjointness-violation` — per scene, `selectedCandidateId`,
 *    `rejectedCandidateIds`, and `pendingCandidateIds` must be pairwise
 *    disjoint.
 *  - `round-gap` — generation rounds within a scene must be contiguous starting
 *    at 1.
 */
export declare function validateSelection(selection: SceneSelectionArtifact, candidates: SceneCandidatesArtifact): ValidationResult;
//# sourceMappingURL=scene-selection.d.ts.map