/**
 * @fileoverview DuckDB-backed {@link IDataCanvasProvider}. One in-memory
 * DuckDB instance per canvasId; a long-lived control connection for DDL and
 * describe operations, plus a per-query connection so cancellation interrupts
 * exactly the in-flight query. `@duckdb/node-api` is lazy-loaded so it stays
 * a true peer dependency.
 * @module src/services/canvas/providers/duckdb/DuckdbProvider
 */
import { type RequestContextLike } from '../../../../utils/internal/requestContext.js';
import type { IDataCanvasProvider } from '../../core/IDataCanvasProvider.js';
import type { DescribeOptions, ExportOptions, ExportResult, ExportTarget, ImportFromOptions, QueryOptions, QueryResult, RegisterRows, RegisterTableOptions, RegisterTableResult, RegisterViewOptions, RegisterViewResult, TableInfo } from '../../types.js';
/** Configuration for {@link DuckdbProvider}. Mirrors the AppConfig.canvas block. */
export interface DuckdbProviderOptions {
    /** Default row cap for `query()` results. */
    defaultRowLimit: number;
    /** Sandbox root for path-targeted exports. */
    exportRootPath: string;
    /** Per-canvas `memory_limit` PRAGMA value, in MB. */
    memoryLimitMb: number;
    /** Number of rows to sniff for schema inference. */
    schemaSniffRows: number;
}
export declare class DuckdbProvider implements IDataCanvasProvider {
    private readonly options;
    readonly name = "duckdb";
    private readonly canvases;
    constructor(options: DuckdbProviderOptions);
    initCanvas(canvasId: string, _context: RequestContextLike): Promise<void>;
    destroyCanvas(canvasId: string, _context: RequestContextLike): Promise<void>;
    healthCheck(): Promise<boolean>;
    shutdown(): Promise<void>;
    registerTable(canvasId: string, name: string, rows: RegisterRows, _context: RequestContextLike, options?: RegisterTableOptions): Promise<RegisterTableResult>;
    query(canvasId: string, sql: string, _context: RequestContextLike, options?: QueryOptions): Promise<QueryResult>;
    export(canvasId: string, tableName: string, target: ExportTarget, _context: RequestContextLike, options?: ExportOptions): Promise<ExportResult>;
    registerView(canvasId: string, name: string, selectSql: string, _context: RequestContextLike, options?: RegisterViewOptions): Promise<RegisterViewResult>;
    importFrom(targetCanvasId: string, sourceCanvasId: string, sourceTableName: string, asName: string, _context: RequestContextLike, options?: ImportFromOptions): Promise<RegisterTableResult>;
    describe(canvasId: string, _context: RequestContextLike, options?: DescribeOptions): Promise<TableInfo[]>;
    private describeOne;
    drop(canvasId: string, name: string, _context: RequestContextLike): Promise<boolean>;
    clear(canvasId: string, _context: RequestContextLike): Promise<number>;
    private requireCanvas;
    /**
     * Run the same four-layer read-only gate `query()` enforces, against an
     * arbitrary SELECT string. Used by `query()` and `registerView()` so view
     * definitions inherit query-level safety.
     */
    private assertReadOnlySql;
    /**
     * Resolve whether a name on the canvas refers to a base table, a view, or
     * nothing. Returns `undefined` when absent; used by drop/registerView/
     * importFrom to dispatch the right DDL.
     */
    private lookupKind;
    /**
     * Materialize `COUNT(*)` against a (validated) table or view name. DuckDB
     * returns BIGINT as a JSON string; this helper centralizes the `Number(...)`
     * coercion so callers see a plain `number`.
     */
    private countRows;
    private runExplain;
}
/**
 * Coerce a value to BigInt without precision loss. `BigInt(Number(value))`
 * round-trips through JS Number and truncates outside the 53-bit safe range,
 * silently corrupting BIGINT IDs returned as numeric strings.
 *
 * @internal Exported for unit testing.
 */
export declare function toBigInt(value: unknown): bigint;
/**
 * Coerce to DuckDB's TIMESTAMP unit (micros since 1970-01-01 UTC, as `bigint`).
 * Accepts `Date`, `bigint` (already-micros), `number` (ms-since-epoch matching
 * `Date.getTime()`), and ISO 8601 strings. Throws `validationError` otherwise.
 *
 * @internal Exported for unit testing.
 */
export declare function toTimestampMicros(value: unknown, columnName: string): bigint;
/**
 * Coerce to DuckDB's DATE unit (days since 1970-01-01 UTC, as `number`).
 * Accepts the same shapes as {@link toTimestampMicros}; throws otherwise.
 *
 * @internal Exported for unit testing.
 */
export declare function toDateDays(value: unknown, columnName: string): number;
/**
 * Coerce to `Uint8Array` for BLOB appends. Accepts `Uint8Array` (Node's
 * `Buffer` passes through as a subclass), `ArrayBuffer`, and any other
 * `ArrayBufferView`. Throws `validationError` for non-binary inputs.
 *
 * @internal Exported for unit testing.
 */
export declare function toUint8Array(value: unknown, columnName: string): Uint8Array;
/**
 * Map a DuckDB-thrown error to a framework error class. Classification is for
 * raw engine errors only — an already-structured `McpError` passes through
 * unchanged (#254): structured throws from inside the provider's try blocks
 * (`ensureTableMissing`'s `register_as_clash`, `resolveExportPath`'s path
 * validations) must keep their code and `data.reason` instead of being
 * reclassified as `DatabaseError`.
 * @internal Exported for unit testing.
 */
export declare function classifyDuckdbError(err: unknown): Error;
//# sourceMappingURL=DuckdbProvider.d.ts.map