/**
 * Owner spot-check for the System One benchmark dataset (T12495).
 *
 * Before any spend, a small random sample stratified by site and label is
 * written to a file. The orchestrator shows each item to the owner through
 * the ask tool (the item carries the proposed label and the allowed labels
 * as ready-made options) and writes the answers to a corrections file.
 * {@link applyBenchCorrections} then relabels (or drops) those rows and marks
 * them owner-verified. Both steps are offline: no provider is contacted.
 *
 * @task T12495
 * @epic T12486
 */
import { z } from 'zod';
import { type BenchRow } from './types.js';
/** Default spot-check sample size. */
export declare const DEFAULT_SPOT_CHECK_SIZE = 30;
/** One item the owner reviews. */
export interface BenchSpotCheckItem {
    /** Dataset row id (the key a correction names). */
    readonly id: string;
    /** Site. */
    readonly site: BenchRow['site'];
    /** The label the builder proposed. */
    readonly proposedLabel: string;
    /** Labels the owner may choose from (the proposed one first). */
    readonly options: readonly string[];
    /** Short, redacted summary of what is being labelled. */
    readonly summary: string;
    /** Why the builder proposed the label. */
    readonly provenance: BenchRow['provenance'];
    /** Already verified by the owner in an earlier round. */
    readonly ownerVerified: boolean;
}
/** The spot-check file. */
export interface BenchSpotCheckFile {
    /** Format version. */
    readonly schemaVersion: 1;
    /** ISO time the sample was drawn. */
    readonly generatedAt: string;
    /** Seed the sample was drawn with. */
    readonly seed: number;
    /** How to answer. */
    readonly instructions: string;
    /** Sampled items. */
    readonly items: readonly BenchSpotCheckItem[];
}
/**
 * Draw a random sample stratified by site and label.
 *
 * @param rows - Dataset rows.
 * @param opts - Sample size (default {@link DEFAULT_SPOT_CHECK_SIZE}) and seed.
 * @returns The spot-check file contents.
 */
export declare function sampleBenchSpotCheck(rows: readonly BenchRow[], opts?: {
    readonly size?: number;
    readonly seed?: number;
    readonly now?: Date;
}): BenchSpotCheckFile;
/** Zod schema of one correction. */
declare const correctionSchema: z.ZodUnion<readonly [z.ZodObject<{
    id: z.ZodString;
    label: z.ZodString;
    note: z.ZodOptional<z.ZodString>;
}, z.core.$strip>, z.ZodObject<{
    id: z.ZodString;
    drop: z.ZodLiteral<true>;
    note: z.ZodOptional<z.ZodString>;
}, z.core.$strip>]>;
/** One owner answer: a label for a row, or a drop. */
export type BenchCorrection = z.infer<typeof correctionSchema>;
/** Outcome of {@link applyBenchCorrections}. */
export interface BenchCorrectionsReceipt {
    /** Rows confirmed with the proposed label. */
    readonly confirmed: number;
    /** Rows relabelled. */
    readonly relabelled: number;
    /** Rows removed. */
    readonly dropped: number;
    /** Correction ids that matched no row. */
    readonly unmatched: readonly string[];
    /** Corrections whose label is not allowed for the row's site (not applied). */
    readonly rejected: readonly {
        readonly id: string;
        readonly label: string;
    }[];
}
/**
 * Parse a corrections file.
 *
 * @param text - File contents (JSON).
 * @returns The corrections.
 * @throws Error when the JSON or its shape is invalid.
 */
export declare function parseBenchCorrections(text: string): BenchCorrection[];
/**
 * Read and parse a corrections file.
 *
 * @param path - Corrections file.
 * @returns The corrections.
 */
export declare function readBenchCorrections(path: string): Promise<BenchCorrection[]>;
/**
 * Apply owner corrections: relabel or drop the named rows and mark every
 * corrected (or confirmed) row owner-verified. A relabelled row keeps its
 * original label in `correctedFrom`.
 *
 * @param rows - Dataset rows.
 * @param corrections - Owner answers.
 * @returns The new rows and a receipt.
 */
export declare function applyBenchCorrections(rows: readonly BenchRow[], corrections: readonly BenchCorrection[]): {
    rows: BenchRow[];
    receipt: BenchCorrectionsReceipt;
};
export {};
//# sourceMappingURL=spot-check.d.ts.map