import type { Reader, RowAdapter } from "./readers.js";
import type { TrainCtx } from "./runtime.js";
/** One file to train: a shard, a per-language file, or a whole single-file
 *  corpus. Exactly one of `url` / `local` is set. */
export interface Unit {
    /** Resume-id suffix — the corpus id and this form `${id}::${key}`. Part of
     *  the store's compatibility surface; see the file header. */
    key: string;
    /** How the run log names this unit once it is read. */
    name: string;
    /** How the live panel names it, and (unless `acquireLabel` overrides) how the
     *  download is labelled. Conventionally `${corpus.label} ${name}`. */
    display: string;
    url?: string;
    local?: string;
    /** Size in bytes when the listing said, else 0/absent. Summed BEFORE the
     *  stage reads anything, so the corpus progress bar has a denominator that
     *  does not grow underneath it. */
    bytes?: number;
    /** Cache filename. Defaults to the resume id with unsafe characters folded. */
    dest?: string;
    /** Download label, when it differs from `display`. */
    acquireLabel?: string;
}
/** How one unit's outcome reads in the run log. All optional: the defaults are
 *  what every fact-shaped corpus prints. */
export interface LogStyle {
    /** What one deposit is called. Default "facts". */
    deposits?: string;
    /** When set, the line reports "from N <rows>" — the count of rows that
     *  actually produced deposits. */
    rows?: string;
    /** What an unusable record is called. Default "unusable row(s)". */
    bad?: string;
    /** Report only the reader's `skipped` (malformed records), not the rows the
     *  adapter declined. For a corpus that DECLINES records by design — oasst2
     *  drops every single-turn tree — counting those as damage would be a lie. */
    malformedOnly?: boolean;
}
export interface Corpus {
    /** Tally key AND resume-id prefix. Compatibility surface — see the header. */
    id: string;
    /** Human name: the panel, the skip notices, the listing-failure message. */
    label: string;
    /** The dim tag in the log line, e.g. "translation", "social dialogue". */
    kind: string;
    enabled: boolean;
    /** The work-list. Return [] for "nothing found" (the runner says so), or
     *  null when the corpus has already logged a more specific reason. */
    discover(ctx: TrainCtx): Promise<Unit[] | null>;
    read: Reader;
    toItems: RowAdapter;
    /** Stage-wide row budget; 0/absent = unbounded. See the budget notes in
     *  stage.ts. */
    maxRows?: number;
    /** Noun for the "N/M ___ to train" announcement. Absent ⇒ no announcement,
     *  which is what a single-unit corpus has always done. */
    unitNoun?: string;
    /** Keep a file that came from the CACHE after a complete read. Only oasst2
     *  does this: every other corpus deletes whatever acquire() handed it. */
    keepCached?: boolean;
    log?: LogStyle;
}
/** The string a store records once this unit is finished. ONE rule, no
 *  exceptions — see the file header for why there used to be two. */
export declare const unitIdOf: (corpus: Corpus, unit: Unit) => string;
/** Local files live under `LOCAL_PATH/<sub>`, or directly in LOCAL_PATH when
 *  `sub` is empty. Kept here because the layout is a user-facing convention:
 *  the corpora that share an extension (.json, .parquet) are kept apart by a
 *  subdirectory so a local run cannot feed one corpus's files to another. */
export declare const localDir: (sub: string) => string;
/** A single-unit corpus: one fixed URL, or one local file matched by pattern.
 *  Factored out because the three corpora that are ONE file resolve it the same
 *  way. `key` is what the store records this corpus under — `aya::dataset` is
 *  `key: "dataset"` — so it is required rather than defaulted: a resume id is
 *  the one thing here that must never be guessed. */
export declare function singleUnit(opts: {
    key: string;
    label: string;
    display: string;
    url: string;
    dest: string;
    acquireLabel?: string;
    /** Patterns tried, in order, against LOCAL_PATH. */
    localMatch: RegExp[];
    /** How the "no local copy" notice describes what it looked for. */
    localWhat: string;
}): (ctx: TrainCtx) => Promise<Unit[] | null>;