/**
 * Pure `hikoutei infer` core: raw grid cells in, descriptor block out.
 *
 * The flow is injectable and network-free: the production CLI reads one tab
 * range through the Sheets API and hands the raw grid here; tests inject a
 * fake grid. Cell normalization ports the provider's getValues semantics
 * (formula cells resolve to their computed effective value, the canonical
 * DATE_TIME number format marks dates, blank stays null) so Sheets-provided
 * typed cell info wins over heuristics — there are no date-format guesses
 * beyond the canonical format the provider itself writes.
 *
 * Source parity notes: the canonical date pattern is byte-identical to
 * `GOOGLE_SHEETS_API_DATE_NUMBER_FORMAT` and the serial math matches
 * `isoFromDateSerial` in the google-sheets-api provider's
 * `model/valueNormalization.ts`. A local port (not an import) keeps the CLI
 * runtime dependency-closed: `@hikoutei/sheets` is not a CLI dependency.
 *
 * Redaction contract: warnings carry COLUMN NAMES ONLY, never cell values.
 */
import { type HikouteiDescriptorFile } from "../sync-engine/api/entity.js";
/** Machine-readable CLI error prefix, shared with inferMain.ts. */
export declare const INFER_ERROR_PREFIX = "hikoutei-infer";
/** Closed set of scalar kinds the inference can emit. */
export type InferScalarType = "string" | "number" | "boolean" | "date";
/** One normalized cell: `null` is an empty cell. */
export type InferCell = null | {
    readonly kind: "string";
    readonly value: string;
} | {
    readonly kind: "number";
    readonly value: number;
} | {
    readonly kind: "boolean";
    readonly value: boolean;
} | {
    readonly kind: "date";
    readonly value: string;
};
/** Raw tab grid handed to the inference (raw Sheets grid cell objects). */
export interface InferTabGrid {
    readonly tabName: string;
    /** Raw grid cells of the header row (rowData values entries). */
    readonly headerCells: readonly unknown[];
    /** Raw grid cells of sampled data rows (rowData values entries per row). */
    readonly dataCells: readonly (readonly unknown[])[];
}
/** Injectable tab sampler; production wraps the Sheets API, tests use fakes. */
export type InferTabReader = (input: {
    readonly spreadsheetId: string;
    readonly tabName: string;
    readonly limit: number;
}) => Promise<InferTabGrid>;
/** One column-name-only inference warning. */
export interface InferWarning {
    readonly column: string;
    readonly reason: string;
}
/** One headed column of a successful inference (feeds `--emit`). */
export interface InferColumn {
    /** Original sheet header, preserved for adopt's column mapping. */
    readonly header: string;
    /** camelCase entity property name derived from the header. */
    readonly property: string;
    /** Inferred scalar type (PK-normalized: a boolean/date PK reads string). */
    readonly type: InferScalarType;
    /** True for the single primary-key/business-key column. */
    readonly primary: boolean;
}
/** Successful inference: the TS block plus its summary. */
export interface InferDescriptorResult {
    readonly entityName: string;
    readonly tableName: string;
    readonly tsBlock: string;
    readonly summary: string;
    readonly warnings: readonly InferWarning[];
    readonly sampledRows: number;
    readonly columnCount: number;
    readonly distribution: Readonly<Record<InferScalarType, number>>;
    readonly pkProperty: string;
    /**
     * Headed columns in sheet order. `--emit` builds the descriptor file
     * from these, so the JSON file and the printed block always agree.
     */
    readonly columns: readonly InferColumn[];
}
/** Coded failure thrown by the pure inference (mapped to stderr + exit 1/2). */
export declare class InferError extends Error {
    readonly code: string;
    constructor(code: string, message: string);
}
/**
 * Normalizes one raw grid cell with getValues semantics: formula cells
 * resolve to their computed effective value, error cells to their display
 * string, literals keep their typed kind, blank cells become `null`.
 */
export declare function normalizeInferCell(cell: unknown): InferCell;
/**
 * Infers the entity descriptor block from a raw tab grid.
 *
 * Throws `InferError`: `empty_tab` (no header row), `pk_not_found` (the
 * `--pk` header names no sampled column). Warnings carry column names only.
 */
export declare function inferFromGrid(grid: InferTabGrid, options?: {
    readonly pkHeader?: string;
}): InferDescriptorResult;
/**
 * Builds the versioned descriptor file for an inference result.
 *
 * Pure and network-free: `--emit` serializes this file next to the printed
 * block, and the file's `header` fields later feed `adopt --descriptor`
 * without manual `--map` flags. Delegates to the contracts builder so the
 * file envelope has one owner; the scalar core matches the printed block
 * column-for-column (same `columns` source), so the two never disagree.
 */
export declare function inferResultToDescriptorFile(result: InferDescriptorResult): HikouteiDescriptorFile;
/** Serializes an inference result to the stable descriptor-file JSON text. */
export declare function serializeInferDescriptorFile(result: InferDescriptorResult): string;
//# sourceMappingURL=infer.d.ts.map