/**
 * The data-program output contract.
 *
 * This module deliberately does NOT touch `../coding-tools/run-code.ts` —
 * `executeSandboxCode` already accepts arbitrary code, so a data program is
 * just user code with a small prelude prepended. The prelude defines a
 * frozen `params` global and a single-call `emit(rows, schema?)` that writes
 * one sentinel-prefixed JSON line to stdout. `parseDataProgramResult` then
 * extracts that line back out of the captured stdout (which may also contain
 * arbitrary `console.log` debug noise before/after it).
 */
export declare const DATA_PROGRAM_SENTINEL = "__DATA_PROGRAM_RESULT__";
export type DataProgramColumnType = "number" | "string" | "boolean" | "json";
export interface DataProgramColumn {
    name: string;
    type: string;
}
export type DataProgramContractErrorCode = "emit_missing" | "emit_shape_invalid" | "result_too_large";
export interface DataProgramContractError {
    code: DataProgramContractErrorCode;
    message: string;
}
export interface ParsedDataProgramResult {
    rows: Record<string, unknown>[];
    schema: DataProgramColumn[];
    truncated: boolean;
}
/**
 * Build the JS source prepended to user code before it is handed to
 * `executeSandboxCode`. Defines:
 *   - a frozen `params` global (deep-frozen best-effort; primitives and
 *     plain JSON values are always frozen, so user code cannot mutate the
 *     params object out from under itself).
 *   - `emit(rows, schema?)` — single-call guard (a second call throws) that
 *     writes `DATA_PROGRAM_SENTINEL + JSON.stringify({rows, schema})` as one
 *     stdout line via `process.stdout.write`. Using `process.stdout.write`
 *     directly (not `console.log`) keeps the sentinel line byte-exact with
 *     no extra formatting, and on its own line so a naive `\n`-split still
 *     finds it even if user code itself never calls `console.log`.
 *
 * `console.log` remains completely free for debugging — the runner captures
 * combined stdout and only strips the sentinel line when parsing.
 */
export declare function buildDataProgramPrelude(params: Record<string, unknown> | undefined): string;
/**
 * Infer a column schema by surveying the first `sampleSize` rows. A column's
 * type is "json" if any sampled row disagrees on primitive type (the safe,
 * always-renderable fallback), otherwise the single agreed primitive type.
 * Columns absent from a row are simply not counted for that row.
 */
export declare function inferDataProgramSchema(rows: Record<string, unknown>[], sampleSize?: number): DataProgramColumn[];
export interface ParseDataProgramResultOptions {
    maxRows: number;
    maxBytes: number;
}
export type ParseDataProgramResultOutcome = {
    ok: true;
    result: ParsedDataProgramResult;
} | {
    ok: false;
    error: DataProgramContractError;
};
/**
 * Parse the sentinel-prefixed emit() payload out of captured sandbox stdout.
 * Never throws — always returns a discriminated outcome with a structured
 * error code so callers can surface something actionable instead of a bare
 * "Error: ..." string.
 */
export declare function parseDataProgramResult(stdout: string, options: ParseDataProgramResultOptions): ParseDataProgramResultOutcome;
//# sourceMappingURL=contract.d.ts.map