/**
 * @copyright Sister Software
 * @license AGPL-3.0
 * @author Teffen Ellis, et al.
 *
 *   Adapter runner — drives a `CorpusAdapter` to completion and writes intermediate JSONL + a
 *   per-shard manifest.
 *
 *   Output layout under `outputDir`:
 *
 *   ```
 *   <outputDir>/<adapter.id>/
 *   canonical.jsonl       # one row per line, in emission order
 *   MANIFEST.json         # adapter id, version, row count, sha256, license, started_at, ended_at
 * ```
 *
 *   The runner is responsible for everything an adapter is **not** responsible for:
 *
 *   - Stamping `corpus_version` on every row (adapters must NOT set it).
 *   - Applying `canonicalDedupKey` and skipping duplicates.
 *   - Streaming sha256 over JSONL bytes so the manifest checksum doesn't require a re-read.
 *   - Honoring backpressure on the output write stream.
 *   - Counting + emitting periodic progress to an optional callback.
 *   - Honoring `signal` (delegates to adapter's iteration boundary).
 *
 *   The runner does NOT perform alignment, tokenization, synthesis, or sharding into Parquet. Those
 *   steps run later, consuming the JSONL shards this writes.
 */
import { type AdapterRegistry } from "@mailwoman/corpus/adapters/utils";
import type { AdapterOptions, CorpusAdapter } from "@mailwoman/corpus/types";
/**
 * Snapshot of the runner's state, emitted on every progress tick.
 */
export interface RunnerProgress {
    /**
     * Adapter being driven.
     */
    adapterID: string;
    /**
     * Total rows the adapter has yielded (before dedup).
     */
    yielded: number;
    /**
     * Rows actually written to JSONL (after dedup).
     */
    written: number;
    /**
     * Bytes written to JSONL so far.
     */
    bytes: number;
    /**
     * Wall-clock milliseconds since the run started.
     */
    elapsed_ms: number;
}
/**
 * Per-invocation options for `runAdapter`.
 */
export interface RunAdapterOptions {
    /**
     * Adapter to drive.
     */
    adapter: CorpusAdapter;
    /**
     * Options handed to the adapter (input path, country filter, limit, signal).
     */
    adapterOptions: AdapterOptions;
    /**
     * Root output directory; the runner creates `<outputDir>/<adapter.id>/` under it.
     */
    outputDir: string;
    /**
     * Corpus version stamped onto every row. Locked together with the tokenizer version.
     */
    corpusVersion: string;
    /**
     * Optional progress callback. Invoked every `progressEvery` rows yielded (default 1000) and once at the end of the
     * run. Errors thrown from this callback abort the run.
     */
    onProgress?: (snapshot: RunnerProgress) => void;
    /**
     * Yielded-row interval at which `onProgress` fires. Defaults to 1000. The terminal tick is always emitted regardless
     * of this value.
     */
    progressEvery?: number;
}
/**
 * Return value of `runAdapter`: the same shape as `MANIFEST.json` on disk.
 */
export interface AdapterRunManifest {
    adapter_id: string;
    corpus_version: string;
    default_license: string;
    description: string;
    yielded: number;
    written: number;
    deduped: number;
    bytes: number;
    sha256: string;
    jsonl_path: string;
    started_at: string;
    ended_at: string;
    elapsed_ms: number;
}
/**
 * Drive a single adapter to completion.
 *
 * Returns the manifest describing the run. Writes `canonical.jsonl` + `MANIFEST.json` under `outputDir/<adapter.id>/`.
 * Throws if the output directory cannot be created, if a row arrives with a missing required field, or if the abort
 * signal fires.
 */
export declare function runAdapter(opts: RunAdapterOptions): Promise<AdapterRunManifest>;
/**
 * Drive every adapter in a registry sequentially. Stops on the first failure (caller can filter the registry before
 * calling if partial-failure is desired).
 *
 * Returns the manifests in registry insertion order.
 */
export declare function runAllAdapters(registry: AdapterRegistry, common: Omit<RunAdapterOptions, "adapter"> & {
    adapterOptionsFor?: (a: CorpusAdapter) => AdapterOptions;
}): Promise<AdapterRunManifest[]>;
/**
 * Convenience: ensure the parent directory of `filePath` exists.
 */
export declare function ensureParentDir(filePath: string): Promise<void>;
//# sourceMappingURL=runner.d.ts.map