lakeql 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1386 @@
+import * as hyparquet_src_types_js from 'hyparquet/src/types.js';
+import { parquetMetadataAsync, RowGroup } from 'hyparquet';
+import { ParquetWriteOptions, ColumnSource, BasicType } from 'hyparquet-writer';
+
+declare const ERROR_CODES: readonly ["LAQL_PARSE_ERROR", "LAQL_TYPE_ERROR", "LAQL_UNKNOWN_TABLE", "LAQL_UNKNOWN_COLUMN", "LAQL_UNSUPPORTED_PUSHDOWN", "LAQL_BUDGET_EXCEEDED", "LAQL_GROUP_LIMIT_EXCEEDED", "LAQL_OBJECT_NOT_FOUND", "LAQL_CATALOG_ERROR", "LAQL_UNSUPPORTED_ICEBERG_FEATURE", "LAQL_UNSUPPORTED_PARQUET_FEATURE", "LAQL_ICEBERG_COMMIT_CONFLICT", "LAQL_UNSUPPORTED_DELETE_FILES", "LAQL_PARQUET_READ_ERROR", "LAQL_PARQUET_WRITE_ERROR", "LAQL_VALIDATION_ERROR", "LAQL_BOOKMARK_STALE", "LAQL_BOOKMARK_INVALID", "LAQL_ABORTED"];
+type LaQLErrorCode = (typeof ERROR_CODES)[number];
+type ErrorDetails = Record<string, unknown>;
+declare class LaQLError extends Error {
+    readonly code: LaQLErrorCode;
+    readonly details: ErrorDetails;
+    constructor(code: LaQLErrorCode, message: string, details?: ErrorDetails);
+}
+declare function isLaQLError(value: unknown): value is LaQLError;
+
+type Scalar = string | number | boolean | bigint | null;
+type CompareOp = "eq" | "ne" | "lt" | "lte" | "gt" | "gte";
+interface LiteralExpr {
+    kind: "literal";
+    value: Scalar;
+}
+interface ColumnExpr {
+    kind: "column";
+    name: string;
+}
+interface CompareExpr {
+    kind: "compare";
+    op: CompareOp;
+    left: Expr;
+    right: Expr;
+}
+interface InExpr {
+    kind: "in";
+    negated: boolean;
+    target: Expr;
+    values: Expr[];
+}
+interface BetweenExpr {
+    kind: "between";
+    target: Expr;
+    low: Expr;
+    high: Expr;
+}
+interface NullCheckExpr {
+    kind: "null-check";
+    negated: boolean;
+    target: Expr;
+}
+interface LogicalExpr {
+    kind: "logical";
+    op: "and" | "or";
+    operands: Expr[];
+}
+interface NotExpr {
+    kind: "not";
+    operand: Expr;
+}
+interface LikeExpr {
+    kind: "like";
+    caseInsensitive: boolean;
+    target: Expr;
+    pattern: string;
+}
+interface CallExpr {
+    kind: "call";
+    fn: string;
+    args: Expr[];
+}
+type Expr = LiteralExpr | ColumnExpr | CompareExpr | InExpr | BetweenExpr | NullCheckExpr | LogicalExpr | NotExpr | LikeExpr | CallExpr;
+/** A value accepted where a column is expected: a column name or any expression. */
+type ColumnInput = string | Expr;
+/** A value accepted where a literal is expected: a scalar or any expression. */
+type ValueInput = Scalar | Expr;
+declare function col(name: string): ColumnExpr;
+declare function lit(value: Scalar): LiteralExpr;
+declare function eq(column: ColumnInput, value: ValueInput): CompareExpr;
+declare function ne(column: ColumnInput, value: ValueInput): CompareExpr;
+declare function lt(column: ColumnInput, value: ValueInput): CompareExpr;
+declare function lte(column: ColumnInput, value: ValueInput): CompareExpr;
+declare function gt(column: ColumnInput, value: ValueInput): CompareExpr;
+declare function gte(column: ColumnInput, value: ValueInput): CompareExpr;
+declare function isIn(column: ColumnInput, values: ValueInput[]): InExpr;
+declare function notIn(column: ColumnInput, values: ValueInput[]): InExpr;
+declare function between(column: ColumnInput, low: ValueInput, high: ValueInput): BetweenExpr;
+declare function isNull(column: ColumnInput): NullCheckExpr;
+declare function isNotNull(column: ColumnInput): NullCheckExpr;
+declare function and(...operands: Expr[]): LogicalExpr;
+declare function or(...operands: Expr[]): LogicalExpr;
+declare function not(operand: Expr): NotExpr;
+declare function like(column: ColumnInput, pattern: string): LikeExpr;
+declare function ilike(column: ColumnInput, pattern: string): LikeExpr;
+/** Generic function-call expression; named functions (h3_*, st_*) build on this. */
+declare function fn(name: string, ...args: ValueInput[]): CallExpr;
+
+type Row = Record<string, unknown>;
+interface BookmarkQuery {
+    source: string;
+    select?: string[];
+    where?: Expr;
+    orderBy?: {
+        column: string;
+        direction?: "asc" | "desc";
+        nulls?: "first" | "last";
+    }[];
+    limit?: number;
+    offset?: number;
+    batchSize?: number;
+    hive?: boolean;
+}
+/**
+ * A serializable position in a running query. Bookmarks are plain values:
+ * the engine only produces and consumes them, and the caller moves them
+ * over whatever transport it likes (queue, KV, URL, cron state).
+ */
+interface Bookmark {
+    version: 1;
+    planFingerprint: string;
+    snapshot: string;
+    query?: BookmarkQuery;
+    position: {
+        fileIndex: number;
+        rowGroup: number;
+        rowOffset: number;
+        taskId?: string;
+        outputManifestCursor?: number;
+    };
+    writeState?: {
+        taskState?: "planned" | "running" | "output-written" | "manifest-recorded" | "complete";
+        idempotencyKey?: string;
+        multipart?: {
+            uploadId: string;
+            path: string;
+            parts: {
+                partNumber: number;
+                etag: string;
+                byteSize: number;
+            }[];
+        };
+    };
+    operatorState?: {
+        limitEmitted?: number;
+        groupBy?: Uint8Array | {
+            spillRef: string;
+        };
+        topK?: Uint8Array | {
+            spillRef: string;
+        };
+        sort?: Uint8Array | {
+            spillRef: string;
+        };
+        sketches?: Record<string, Uint8Array>;
+    };
+}
+interface SliceResult {
+    rows: Row[];
+    /** Absent when the query completed. */
+    bookmark?: Bookmark;
+}
+interface QueryStats {
+    queryId: string;
+    elapsedMs: number;
+    manifestsRead: number;
+    manifestsSkipped: number;
+    filesPlanned: number;
+    filesRead: number;
+    filesSkipped: number;
+    rowGroupsRead: number;
+    rowGroupsSkipped: number;
+    columnsRead: string[];
+    bytesRequested: number;
+    rangeRequests: number;
+    rowsDecoded: number;
+    rowsMatched: number;
+    rowsReturned: number;
+    cacheHits: number;
+    cacheMisses: number;
+}
+
+type SqlBoolean = boolean | null;
+type EvalValue = Scalar;
+declare function evaluate(expr: Expr, row: Row): EvalValue;
+declare function matches(expr: Expr | undefined, row: Row): boolean;
+declare function jsonSafeValue(value: unknown): unknown;
+declare function encodeJsonLine(row: Row): Uint8Array;
+
+type JoinType = "inner" | "left" | "semi" | "anti";
+interface BroadcastJoinOptions {
+    leftKey: string;
+    rightKey: string;
+    maxRightRows: number;
+    type?: JoinType;
+    rightPrefix?: string;
+}
+interface LookupJoinOptions {
+    leftKey: string;
+    rightKey: string;
+    maxRightRows: number;
+    type?: JoinType;
+    rightPrefix?: string;
+}
+type LookupJoinFunction = (key: string | number | boolean | bigint | null, leftRow: Row) => AsyncIterable<Row> | Iterable<Row> | Promise<AsyncIterable<Row> | Iterable<Row>>;
+declare function broadcastJoin(left: AsyncIterable<Row> | Iterable<Row>, right: AsyncIterable<Row> | Iterable<Row>, options: BroadcastJoinOptions): Promise<Row[]>;
+declare function lookupJoin(left: AsyncIterable<Row> | Iterable<Row>, lookup: LookupJoinFunction, options: LookupJoinOptions): Promise<Row[]>;
+
+interface PredicatePlan {
+    partition: Expr[];
+    fileStats: Expr[];
+    rowGroupStats: Expr[];
+    residual: Expr[];
+}
+interface PredicatePlanOptions {
+    partitionColumns?: Iterable<string>;
+    fileStatsColumns?: Iterable<string>;
+    rowGroupStatsColumns?: Iterable<string>;
+}
+declare function classifyPredicate(expr: Expr | undefined, options?: PredicatePlanOptions): PredicatePlan;
+
+interface CacheEntry<T> {
+    value: T;
+    expiresAt?: number;
+}
+interface CacheAdapter<T = Uint8Array> {
+    get(key: string): Promise<CacheEntry<T> | undefined>;
+    set(key: string, entry: CacheEntry<T>): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+declare class MemoryCache<T = Uint8Array> implements CacheAdapter<T> {
+    private readonly entries;
+    get(key: string): Promise<CacheEntry<T> | undefined>;
+    set(key: string, entry: CacheEntry<T>): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+declare function memoryCache<T = Uint8Array>(): CacheAdapter<T>;
+interface CacheApiCacheOptions {
+    namespace?: string;
+    now?: () => number;
+}
+declare class CacheApiCache implements CacheAdapter<Uint8Array> {
+    private readonly cache;
+    private readonly namespace;
+    private readonly now;
+    constructor(cache: Cache, options?: CacheApiCacheOptions);
+    get(key: string): Promise<CacheEntry<Uint8Array> | undefined>;
+    set(key: string, entry: CacheEntry<Uint8Array>): Promise<void>;
+    delete(key: string): Promise<void>;
+    private request;
+}
+declare function cacheApiCache(cache: Cache, options?: CacheApiCacheOptions): CacheAdapter<Uint8Array>;
+interface CheckpointStore {
+    get(jobId: string): Promise<Bookmark | undefined>;
+    put(jobId: string, bookmark: Bookmark): Promise<void>;
+    delete(jobId: string): Promise<void>;
+}
+interface SpillRef {
+    id: string;
+    byteSize: number;
+}
+interface SpillUsage {
+    entries: number;
+    byteSize: number;
+}
+interface SpillAdapter {
+    write(id: string, data: Uint8Array): Promise<SpillRef>;
+    read(ref: SpillRef | string): Promise<Uint8Array>;
+    delete(ref: SpillRef | string): Promise<void>;
+    usage(): Promise<SpillUsage>;
+}
+interface MemorySpillAdapterOptions {
+    maxBytes?: number;
+}
+declare class MemorySpillAdapter implements SpillAdapter {
+    private readonly entries;
+    private readonly maxBytes;
+    constructor(options?: MemorySpillAdapterOptions);
+    write(id: string, data: Uint8Array): Promise<SpillRef>;
+    read(ref: SpillRef | string): Promise<Uint8Array>;
+    delete(ref: SpillRef | string): Promise<void>;
+    usage(): Promise<SpillUsage>;
+    private currentBytes;
+}
+declare function memorySpillAdapter(options?: MemorySpillAdapterOptions): SpillAdapter;
+interface QueueAdapter<T> {
+    send(message: T, options?: {
+        delayMs?: number;
+    }): Promise<void>;
+}
+interface LockAdapter {
+    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+interface Clock {
+    now(): number;
+}
+interface IdGenerator {
+    id(prefix?: string): string;
+}
+interface MetricsHook {
+    count(name: string, value?: number, tags?: Record<string, string>): void;
+    timing(name: string, ms: number, tags?: Record<string, string>): void;
+}
+interface LogHook {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+interface RuntimeSubstrate {
+    checkpointStore?: CheckpointStore;
+    spill?: SpillAdapter;
+    queue?: QueueAdapter<Bookmark>;
+    lock?: LockAdapter;
+    clock?: Clock;
+    ids?: IdGenerator;
+    metrics?: MetricsHook;
+    log?: LogHook;
+}
+
+type IndexValue = string | number | bigint | boolean;
+interface MinMaxColumnIndex {
+    min: IndexValue;
+    max: IndexValue;
+    nullCount?: number;
+}
+interface BBoxIndex {
+    minx: number;
+    miny: number;
+    maxx: number;
+    maxy: number;
+}
+interface SidecarFileIndex {
+    path: string;
+    columns?: Record<string, MinMaxColumnIndex>;
+    bbox?: Record<string, BBoxIndex>;
+    h3?: Record<string, string[]>;
+}
+interface IndexPruneResult<T extends SidecarFileIndex = SidecarFileIndex> {
+    planned: T[];
+    skipped: T[];
+}
+declare function pruneFilesWithIndex<T extends SidecarFileIndex>(files: T[], where: Expr | undefined): IndexPruneResult<T>;
+declare function bboxMayIntersect(index: BBoxIndex, query: BBoxIndex): boolean;
+declare function buildMinMaxIndex<T extends Record<string, unknown>>(rows: T[], columns: string[]): Record<string, MinMaxColumnIndex>;
+declare function buildBBoxIndex<T extends Record<string, unknown>>(rows: T[], columns: {
+    minx: string;
+    miny: string;
+    maxx: string;
+    maxy: string;
+}): BBoxIndex;
+
+interface PutOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+}
+interface ConditionalPutOptions extends PutOptions {
+    /**
+     * ETag that must still identify the existing object. Use null to require
+     * the object to be absent.
+     */
+    expectedEtag: string | null;
+}
+interface ListOptions {
+    /** Stop listing after this many objects. */
+    limit?: number;
+    /** List "directories" by stopping at this delimiter. */
+    delimiter?: string;
+}
+interface ObjectInfo {
+    path: string;
+    size: number;
+    etag?: string;
+    lastModified?: Date;
+}
+interface ObjectHead {
+    size: number;
+    etag?: string;
+    lastModified?: Date;
+    contentType?: string;
+}
+/**
+ * The single environmental contract for storage. Every runtime driver
+ * (R2, S3, HTTP, filesystem) supplies one of these; core never touches
+ * a runtime API directly.
+ */
+interface ObjectStore {
+    get(path: string): Promise<Uint8Array | null>;
+    getRange(path: string, range: {
+        offset: number;
+        length: number;
+    }): Promise<Uint8Array>;
+    put(path: string, body: Uint8Array | ReadableStream<Uint8Array>, options?: PutOptions): Promise<void>;
+    delete(path: string): Promise<void>;
+    list(prefix: string, options?: ListOptions): AsyncIterable<ObjectInfo>;
+    head(path: string): Promise<ObjectHead | null>;
+}
+interface ConditionalObjectStore extends ObjectStore {
+    conditionalPut(path: string, body: Uint8Array | ReadableStream<Uint8Array>, options: ConditionalPutOptions): Promise<boolean>;
+}
+interface ObjectStoreReadControls {
+    maxConcurrentReads?: number;
+    signal?: AbortSignal;
+    maxElapsedMs?: number;
+}
+declare function withObjectStoreReadControls(store: ObjectStore, controls: ObjectStoreReadControls): ObjectStore;
+declare function readControlSignal(controls: ObjectStoreReadControls): AbortSignal | undefined;
+declare function throwIfAborted(signal: AbortSignal | undefined): void;
+
+interface QueryBudget {
+    maxFiles?: number;
+    maxBytes?: number;
+    maxRowsDecoded?: number;
+    maxOutputRows?: number;
+    maxRangeRequests?: number;
+    maxElapsedMs?: number;
+    /** Maximum rows an operator may buffer in memory for orderBy/top-k work. */
+    maxBufferedRows?: number;
+    /** Maximum deterministic serialized bytes an in-memory operator may retain. */
+    maxMemoryBytes?: number;
+    /** Maximum object-store reads allowed to be in flight at once. */
+    maxConcurrentReads?: number;
+    /** Abort query planning or scanning at await boundaries. */
+    signal?: AbortSignal;
+}
+type QueryPolicyContext = Record<string, unknown>;
+interface QueryPolicy {
+    /** Restrict visible and predicate columns. When no select is supplied, this becomes the projection. */
+    allowedColumns?: string[];
+    /** Hard cap on rows returned by a query, applied even when the caller omits limit. */
+    maxLimit?: number;
+    /** Additional caller-owned predicate applied to every query. */
+    rowFilter?: Expr | ((context: QueryPolicyContext) => Expr | undefined);
+    context?: QueryPolicyContext;
+}
+interface LakeConfig {
+    store: ObjectStore;
+    scanner: ScanAdapter;
+    sidecarIndex?: SidecarFileIndex[];
+    budget?: QueryBudget;
+    policy?: QueryPolicy;
+    substrate?: RuntimeSubstrate;
+    now?: () => number;
+    queryId?: () => string;
+}
+interface ScanOptions {
+    columns?: string[];
+    where?: Expr;
+    batchSize: number;
+    stats: QueryStats;
+    budget: QueryBudget;
+    now: () => number;
+    startedAt: number;
+}
+interface ScanAdapter {
+    scan(path: string, options: ScanOptions): AsyncIterable<Row[]>;
+    planTask?(path: string, options: ScanTaskPlanOptions): Promise<ScanTaskPlan>;
+}
+interface ScanTaskPlanOptions {
+    columns?: string[];
+    where?: Expr;
+    partitionValues: Record<string, string>;
+}
+interface ScanTaskPlan {
+    rowGroupRanges: {
+        start: number;
+        end: number;
+    }[];
+}
+interface PathQueryInit {
+    source: string;
+    select?: string[];
+    where?: Expr;
+    orderBy?: OrderByTerm[];
+    limit?: number;
+    offset?: number;
+    batchSize?: number;
+    hive?: boolean;
+}
+interface OrderByTerm {
+    column: string;
+    direction?: "asc" | "desc";
+    nulls?: "first" | "last";
+}
+interface SliceOptions {
+    maxRows: number;
+    bookmark?: Bookmark;
+}
+interface QueryRunOptions {
+    slice: SliceOptions;
+}
+interface ResumableBatchOptions {
+    bookmarkEvery: number;
+    bookmark?: Bookmark;
+}
+interface CsvStreamOptions {
+    /** Emit the header row. Defaults to true. */
+    header?: boolean;
+    /** Column order for CSV output. Defaults to select columns or first-row keys. */
+    columns?: string[];
+}
+type AggregateOp = "count" | "sum" | "avg" | "min" | "max" | "count_distinct" | "approx_count_distinct" | "first" | "last" | "any";
+interface AggregateExpr {
+    op: AggregateOp;
+    column?: string;
+}
+type AggregateSpec = Record<string, AggregateExpr>;
+interface AggregateOptions {
+    maxGroups?: number;
+    operatorState?: Uint8Array | AggregateOperatorState | {
+        spillRef: string;
+    };
+    spill?: SpillAdapter;
+    spillId?: string;
+}
+interface AggregateResult {
+    rows: Row[];
+    operatorState: Uint8Array;
+    operatorSpill?: SpillRef;
+}
+interface TopKOptions {
+    operatorState?: Uint8Array | TopKOperatorState | {
+        spillRef: string;
+    };
+    spill?: SpillAdapter;
+    spillId?: string;
+}
+interface TopKResult {
+    rows: Row[];
+    operatorState: Uint8Array;
+    operatorSpill?: SpillRef;
+}
+interface SortOptions {
+    operatorState?: Uint8Array | SortOperatorState | {
+        spillRef: string;
+    };
+    spill?: SpillAdapter;
+    spillId?: string;
+}
+interface SortResult {
+    rows: Row[];
+    operatorState: Uint8Array;
+    operatorSpill?: SpillRef;
+}
+interface SortOperatorState {
+    version: 1;
+    orderBy: OrderByTerm[];
+    runs: SortRunState[];
+}
+type SortRunState = {
+    rows: Record<string, OperatorSnapshotValue>[];
+} | {
+    spillRef: string;
+    rowCount: number;
+    byteSize: number;
+};
+interface TopKOperatorState {
+    version: 1;
+    orderBy: OrderByTerm[];
+    offset: number;
+    limit: number;
+    rows: Record<string, OperatorSnapshotValue>[];
+}
+type OperatorSnapshotValue = string | number | boolean | null;
+type AggregateSnapshotValue = OperatorSnapshotValue;
+interface AggregateOperatorState {
+    version: 1;
+    groupColumns: string[];
+    spec: AggregateSpec;
+    groups: AggregateGroupSnapshot[];
+}
+interface AggregateGroupSnapshot {
+    key: string;
+    keys: Record<string, AggregateSnapshotValue>;
+    states: Record<string, AggregateStateSnapshot>;
+}
+type AggregateStateSnapshot = {
+    op: "count";
+    count: number;
+} | {
+    op: "sum";
+    sum: number;
+} | {
+    op: "avg";
+    sum: number;
+    count: number;
+} | {
+    op: "min" | "max";
+    value: AggregateSnapshotValue;
+} | {
+    op: "count_distinct" | "approx_count_distinct";
+    values: string[];
+} | {
+    op: "first" | "last" | "any";
+    seen: boolean;
+    value: AggregateSnapshotValue;
+};
+interface TaskInput {
+    path: string;
+    etag?: string;
+    size?: number;
+    rowGroupRanges: {
+        start: number;
+        end: number;
+    }[];
+    projectedColumns?: string[];
+    residualPredicate?: Expr;
+    partitionValues: Record<string, string>;
+}
+interface ExplainJson {
+    queryId: string;
+    filesPlanned: number;
+    filesSkipped: number;
+    projectedColumns: string[];
+    predicatePlan: PredicatePlan;
+    tasks: TaskInput[];
+}
+interface ExplainResult {
+    text: string;
+    json: ExplainJson;
+}
+interface JsonQueryV1 {
+    version: 1;
+    from: string;
+    select?: string[];
+    where?: JsonExpr;
+    orderBy?: JsonOrderByTerm[];
+    limit?: number;
+    offset?: number;
+}
+interface JsonOrderByTerm {
+    column: string;
+    direction?: "asc" | "desc";
+    nulls?: "first" | "last";
+}
+type JsonExpr = {
+    eq: [string, unknown];
+} | {
+    ne: [string, unknown];
+} | {
+    lt: [string, unknown];
+} | {
+    lte: [string, unknown];
+} | {
+    gt: [string, unknown];
+} | {
+    gte: [string, unknown];
+} | {
+    in: [string, unknown[]];
+} | {
+    notIn: [string, unknown[]];
+} | {
+    between: [string, unknown, unknown];
+} | {
+    isNull: string;
+} | {
+    isNotNull: string;
+} | {
+    like: [string, string];
+} | {
+    ilike: [string, string];
+} | {
+    and: JsonExpr[];
+} | {
+    or: JsonExpr[];
+} | {
+    not: JsonExpr;
+};
+declare class Lake {
+    readonly store: ObjectStore;
+    private readonly scanner;
+    private readonly budget;
+    private readonly policy;
+    private readonly now;
+    private readonly queryId;
+    private readonly substrate;
+    private readonly sidecarIndex;
+    constructor(config: LakeConfig);
+    path(source: string): QueryBuilder;
+    hive(source: string): QueryBuilder;
+    query(input: JsonQueryV1): QueryBuilder;
+    resume(bookmark: Bookmark): ResumedQuery;
+    createResult(init: PathQueryInit): QueryResult;
+}
+declare class ResumedQuery {
+    private readonly lake;
+    private readonly bookmark;
+    constructor(lake: Lake, bookmark: Bookmark);
+    run(options: QueryRunOptions): Promise<SliceResult>;
+}
+declare class QueryBuilder {
+    private readonly lake;
+    private readonly init;
+    constructor(lake: Lake, init: PathQueryInit);
+    select(columns: string[]): QueryBuilder;
+    where(expr: Expr): QueryBuilder;
+    orderBy(terms: OrderByTerm[]): QueryBuilder;
+    limit(limit: number): QueryBuilder;
+    offset(offset: number): QueryBuilder;
+    batchSize(batchSize: number): QueryBuilder;
+    explain(): Promise<ExplainResult>;
+    planTasks(): Promise<TaskInput[]>;
+    taskManifest(jobId?: string): Promise<TaskManifest>;
+    run(): QueryResult;
+    run(options: QueryRunOptions): Promise<SliceResult>;
+    rows(): AsyncIterable<Row>;
+    batches(): AsyncIterable<Row[]>;
+    toArray(): Promise<Row[]>;
+    topKWithState(options?: TopKOptions): Promise<TopKResult>;
+    sortWithState(options?: SortOptions): Promise<SortResult>;
+    first(): Promise<Row | undefined>;
+    count(): Promise<number>;
+    streamNdjson(): ReadableStream<Uint8Array>;
+    streamJson(): ReadableStream<Uint8Array>;
+    streamCsv(options?: CsvStreamOptions): ReadableStream<Uint8Array>;
+    resumableBatches(options: ResumableBatchOptions): AsyncIterable<SliceResult>;
+    groupBy(columns: string[]): AggregationBuilder;
+}
+declare class AggregationBuilder {
+    private readonly result;
+    private readonly columns;
+    constructor(result: QueryResult, columns: string[]);
+    aggregate(spec: AggregateSpec, options?: AggregateOptions): Promise<Row[]>;
+    aggregateWithState(spec: AggregateSpec, options?: AggregateOptions): Promise<AggregateResult>;
+}
+interface QueryResultConfig extends PathQueryInit {
+    lake: Lake;
+    bookmarkQuery: BookmarkQuery;
+    scanner: ScanAdapter;
+    budget: QueryBudget;
+    now: () => number;
+    queryId: string;
+    metrics?: MetricsHook;
+    sidecarIndex?: SidecarFileIndex[];
+}
+declare class QueryResult {
+    readonly stats: QueryStats;
+    private readonly config;
+    constructor(config: QueryResultConfig);
+    rows(): AsyncIterable<Row>;
+    private matchedRows;
+    batches(): AsyncIterable<Row[]>;
+    toArray(): Promise<Row[]>;
+    topKWithState(options?: TopKOptions): Promise<TopKResult>;
+    sortWithState(options?: SortOptions): Promise<SortResult>;
+    first(): Promise<Row | undefined>;
+    count(): Promise<number>;
+    planTasks(): Promise<TaskInput[]>;
+    taskManifest(jobId?: string): Promise<TaskManifest>;
+    slice(options: SliceOptions): Promise<SliceResult>;
+    resumableBatches(options: ResumableBatchOptions): AsyncIterable<SliceResult>;
+    aggregate(groupColumns: string[], spec: AggregateSpec, options?: AggregateOptions): Promise<Row[]>;
+    aggregateWithState(groupColumns: string[], spec: AggregateSpec, options?: AggregateOptions): Promise<AggregateResult>;
+    private orderedBatches;
+    private collectOrderedMatches;
+    private collectSortRuns;
+    explain(): Promise<ExplainResult>;
+    private tasksFromObjects;
+    private planObjects;
+    streamNdjson(): ReadableStream<Uint8Array>;
+    streamJson(): ReadableStream<Uint8Array>;
+    streamCsv(options?: CsvStreamOptions): ReadableStream<Uint8Array>;
+}
+declare function serializeAggregateOperatorState(state: AggregateOperatorState): Uint8Array;
+declare function deserializeAggregateOperatorState(bytes: Uint8Array | AggregateOperatorState): AggregateOperatorState;
+declare function serializeTopKOperatorState(state: TopKOperatorState): Uint8Array;
+declare function serializeSortOperatorState(state: SortOperatorState): Uint8Array;
+declare function deserializeTopKOperatorState(bytes: Uint8Array | TopKOperatorState): TopKOperatorState;
+declare function deserializeSortOperatorState(bytes: Uint8Array | SortOperatorState): SortOperatorState;
+declare function parseJsonQuery(input: unknown): PathQueryInit;
+declare function parseHivePartitions(path: string): Record<string, string>;
+
+interface TaskManifestTask {
+    id: string;
+    input: TaskInput;
+    outputRole: "rows" | "data-file" | "manifest";
+}
+interface TaskManifest {
+    version: 1;
+    jobId: string;
+    planFingerprint: string;
+    snapshot: string;
+    tasks: TaskManifestTask[];
+}
+interface OutputManifestEntry {
+    taskId: string;
+    outputPath: string;
+    partitionValues: Record<string, string>;
+    rowCount: number;
+    byteSize: number;
+    contentHash?: string;
+    etag?: string;
+    iceberg?: {
+        recordCount: number;
+        fileSizeInBytes: number;
+        partitionValues: Record<string, string>;
+    };
+}
+interface OutputManifest {
+    version: 1;
+    jobId: string;
+    planFingerprint: string;
+    entries: OutputManifestEntry[];
+}
+type TaskState = "planned" | "running" | "output-written" | "manifest-recorded" | "complete";
+interface TaskCheckpoint {
+    taskId: string;
+    state: TaskState;
+    idempotencyKey: string;
+    updatedAtMs: number;
+    output?: OutputManifestEntry;
+    outputs?: OutputManifestEntry[];
+}
+interface CheckpointAdapter {
+    get(taskId: string): Promise<TaskCheckpoint | undefined>;
+    put(checkpoint: TaskCheckpoint): Promise<void>;
+    list(jobId?: string): AsyncIterable<TaskCheckpoint>;
+}
+interface TaskTransitionInput {
+    taskId: string;
+    nextState: TaskState;
+    idempotencyKey: string;
+    nowMs: number;
+    staleTimeoutMs?: number;
+    output?: OutputManifestEntry;
+    outputs?: OutputManifestEntry[];
+}
+interface BookmarkPosition {
+    fileIndex: number;
+    rowGroup: number;
+    rowOffset: number;
+    taskId?: string;
+    outputManifestCursor?: number;
+}
+interface BookmarkInit {
+    planFingerprint: string;
+    snapshot: string;
+    query?: BookmarkQuery;
+    position: BookmarkPosition;
+    writeState?: Bookmark["writeState"];
+    operatorState?: Bookmark["operatorState"];
+}
+declare function createTaskManifest(input: {
+    jobId: string;
+    snapshot?: string;
+    tasks: TaskInput[];
+    outputRole?: TaskManifestTask["outputRole"];
+}): TaskManifest;
+declare function createOutputManifest(input: {
+    jobId: string;
+    planFingerprint: string;
+    entries: OutputManifestEntry[];
+}): OutputManifest;
+declare function createOutputManifestFromCheckpoints(input: {
+    jobId: string;
+    planFingerprint: string;
+    checkpoints: CheckpointAdapter;
+}): Promise<OutputManifest>;
+declare function writeOutputManifest(store: ObjectStore, path: string, manifest: OutputManifest): Promise<{
+    path: string;
+    byteSize: number;
+    etag?: string;
+}>;
+declare function readOutputManifest(store: ObjectStore, path: string): Promise<OutputManifest>;
+declare function createBookmark(init: BookmarkInit): Bookmark;
+declare function assertBookmarkMatches(bookmark: Bookmark, planFingerprint: string): void;
+declare function signPaginationToken(bookmark: Bookmark, secret: string | Uint8Array): Promise<string>;
+declare function verifyPaginationToken(token: string, secret: string | Uint8Array): Promise<Bookmark>;
+declare class MemoryCheckpointAdapter implements CheckpointAdapter {
+    private readonly checkpoints;
+    private readonly taskJobs;
+    get(taskId: string): Promise<TaskCheckpoint | undefined>;
+    put(checkpoint: TaskCheckpoint): Promise<void>;
+    list(jobId?: string): AsyncIterable<TaskCheckpoint>;
+}
+declare function memoryCheckpointAdapter(): MemoryCheckpointAdapter;
+declare function advanceTaskCheckpoint(checkpoints: CheckpointAdapter, input: TaskTransitionInput): Promise<TaskCheckpoint>;
+declare function transitionTaskCheckpoint(existing: TaskCheckpoint | undefined, input: TaskTransitionInput): TaskCheckpoint;
+declare function stableStringify(value: unknown): string;
+declare function fingerprint(value: unknown): string;
+
+/**
+ * In-memory ObjectStore. The reference implementation of the store
+ * contract, used by tests and usable as a small read-through cache.
+ */
+declare class MemoryObjectStore implements ObjectStore {
+    private readonly objects;
+    private version;
+    get(path: string): Promise<Uint8Array | null>;
+    getRange(path: string, range: {
+        offset: number;
+        length: number;
+    }): Promise<Uint8Array>;
+    put(path: string, body: Uint8Array | ReadableStream<Uint8Array>, options?: PutOptions): Promise<void>;
+    conditionalPut(path: string, body: Uint8Array | ReadableStream<Uint8Array>, options: ConditionalPutOptions): Promise<boolean>;
+    private writeObject;
+    delete(path: string): Promise<void>;
+    list(prefix: string, options?: ListOptions): AsyncIterable<ObjectInfo>;
+    head(path: string): Promise<ObjectHead | null>;
+}
+declare function memoryStore(): MemoryObjectStore;
+
+declare const PACKAGE: "@laql/iceberg";
+type IcebergReadMode = "strict" | "ignore-deletes" | "ignore-unsupported-deletes";
+interface LoadIcebergTableOptions extends ObjectStoreReadControls {
+    store: ObjectStore;
+    metadataPath: string;
+}
+interface LoadIcebergTableFromObjectStoreOptions extends ObjectStoreReadControls {
+    store: ObjectStore;
+    tableLocation: string;
+}
+interface IcebergRestCatalogOptions {
+    url: string;
+    namespace: string | string[];
+    table: string;
+    prefix?: string;
+    token?: string;
+    fetch?: typeof fetch;
+}
+interface IcebergGlueCatalogOptions {
+    region: string;
+    namespace: string | string[];
+    table: string;
+    catalogId?: string;
+}
+interface IcebergNessieCatalogOptions {
+    url: string;
+    namespace: string | string[];
+    table: string;
+    ref?: string;
+    token?: string;
+}
+interface LoadIcebergTableFromRestOptions extends IcebergRestCatalogOptions, ObjectStoreReadControls {
+    store: ObjectStore;
+}
+interface PlanIcebergFilesOptions {
+    snapshotId?: number;
+    asOfTimestampMs?: number;
+    ref?: string;
+    where?: Expr;
+    select?: string[];
+    readMode?: IcebergReadMode;
+}
+interface ProjectIcebergRowOptions {
+    snapshotId?: number;
+    asOfTimestampMs?: number;
+    ref?: string;
+    select?: string[];
+}
+interface IcebergAppendFile {
+    path: string;
+    partition?: Record<string, string>;
+    recordCount: number;
+    fileSizeInBytes: number;
+}
+interface IcebergAppendOptions {
+    files: IcebergAppendFile[];
+    jobId?: string;
+    nowMs?: number;
+    nextSnapshotId?: number;
+    catalog?: IcebergCommitCatalog;
+}
+interface IcebergAppendOutputManifestOptions extends Omit<IcebergAppendOptions, "files" | "jobId"> {
+    manifest: OutputManifest;
+}
+interface IcebergCommitCatalog {
+    commitAppend(input: IcebergCommitInput): Promise<boolean | IcebergCommitResult>;
+}
+interface IcebergCatalog extends IcebergCommitCatalog {
+    loadTable(store: ObjectStore): Promise<IcebergTable>;
+    listTables(): Promise<IcebergTableIdentifier[]>;
+}
+interface IcebergTableIdentifier {
+    namespace: string[];
+    name: string;
+}
+interface IcebergCommitResult {
+    committed: boolean;
+    metadataPath?: string;
+}
+interface IcebergCommitInput {
+    store: ObjectStore;
+    currentMetadataPath: string;
+    nextMetadataPath: string;
+    expectedSnapshotId: number;
+    nextSnapshotId: number;
+    manifestPath: string;
+    manifest: Manifest;
+    metadata: MetadataFile;
+}
+interface IcebergAppendResult {
+    snapshotId: number;
+    previousSnapshotId: number;
+    metadataPath: string;
+    manifestPath: string;
+    files: PlannedIcebergFile[];
+}
+interface IcebergField {
+    id: number;
+    name: string;
+    sourceId?: number;
+    type: string;
+    required: boolean;
+}
+interface PlannedIcebergFile {
+    path: string;
+    sequenceNumber: number;
+    partition: Record<string, string>;
+    recordCount: number;
+    fileSizeInBytes?: number;
+    projectedFieldIds: number[];
+    snapshotId: number;
+    deleteFiles?: IcebergDeleteFile[];
+}
+interface IcebergDeleteFile {
+    content: "position-delete" | "equality-delete" | "deletion-vector";
+    path: string;
+}
+interface IcebergPlan {
+    snapshotId: number;
+    schemaId: number;
+    manifestsRead: number;
+    manifestsSkipped: number;
+    filesPlanned: number;
+    filesSkipped: number;
+    deleteFilesPlanned: number;
+    deleteFilesIgnored: number;
+    files: PlannedIcebergFile[];
+}
+interface IcebergPositionDelete {
+    path: string;
+    position: number;
+}
+interface IcebergEqualityDelete {
+    columns: string[];
+    row: Row;
+}
+interface IcebergDeletionVector {
+    path: string;
+    positions: number[];
+}
+interface ApplyIcebergDeletesOptions {
+    dataFilePath: string;
+    rows: Row[];
+    rowOffset?: number;
+    positionDeletes?: IcebergPositionDelete[];
+    equalityDeletes?: IcebergEqualityDelete[];
+    deletionVectors?: IcebergDeletionVector[];
+}
+interface DecodedIcebergDeletes {
+    positionDeletes?: IcebergPositionDelete[];
+    equalityDeletes?: IcebergEqualityDelete[];
+    deletionVectors?: IcebergDeletionVector[];
+}
+interface IcebergRowBatch {
+    rowOffset: number;
+    rows: Row[];
+}
+interface ScanPlannedIcebergRowsOptions extends ObjectStoreReadControls {
+    plan: IcebergPlan | PlannedIcebergFile[];
+    readDataFile(file: PlannedIcebergFile): Promise<Row[] | AsyncIterable<Row[] | IcebergRowBatch>>;
+    readDeleteFile(deleteFile: IcebergDeleteFile, dataFile: PlannedIcebergFile): Promise<DecodedIcebergDeletes>;
+}
+interface MetadataFile {
+    "format-version": number;
+    "table-uuid": string;
+    location: string;
+    "current-snapshot-id": number;
+    refs?: Record<string, {
+        type: "branch" | "tag";
+        "snapshot-id": number;
+    }>;
+    schemas: {
+        "schema-id": number;
+        fields: IcebergField[];
+    }[];
+    snapshots: Snapshot[];
+    "partition-specs"?: IcebergPartitionSpec[];
+    "sort-orders"?: IcebergSortOrder[];
+}
+interface IcebergPartitionSpec {
+    "spec-id": number;
+    fields: IcebergPartitionField[];
+}
+interface IcebergPartitionField {
+    "source-id": number;
+    "field-id": number;
+    name: string;
+    transform: string;
+}
+interface IcebergSortOrder {
+    "order-id": number;
+    fields: unknown[];
+}
+interface Snapshot {
+    "snapshot-id": number;
+    "timestamp-ms": number;
+    "schema-id": number;
+    "manifest-list"?: string;
+    manifests?: Manifest[];
+}
+interface Manifest {
+    path: string;
+    files: ManifestFile[];
+    deleteFiles?: ManifestDeleteFile[];
+}
+interface ManifestFile {
+    path: string;
+    sequenceNumber: number;
+    partition?: Record<string, string>;
+    recordCount: number;
+    fileSizeInBytes?: number;
+    deleteFiles?: ManifestDeleteFile[];
+}
+interface ManifestDeleteFile {
+    content: string;
+    path: string;
+    partition?: Record<string, string>;
+}
+declare class IcebergTable {
+    private readonly store;
+    readonly metadataPath: string;
+    readonly metadata: MetadataFile;
+    constructor(store: ObjectStore, metadataPath: string, metadata: MetadataFile);
+    snapshot(options?: PlanIcebergFilesOptions): Snapshot;
+    schema(schemaId: number): IcebergField[];
+    projectRow(row: Row, options?: ProjectIcebergRowOptions): Row;
+    planFiles(options?: PlanIcebergFilesOptions): IcebergPlan;
+    appendFiles(options: IcebergAppendOptions): Promise<IcebergAppendResult>;
+    appendOutputManifest(options: IcebergAppendOutputManifestOptions): Promise<IcebergAppendResult>;
+    private snapshotById;
+    private fieldNameById;
+}
+declare class ObjectStoreIcebergCommitCatalog implements IcebergCommitCatalog {
+    commitAppend(input: IcebergCommitInput): Promise<IcebergCommitResult>;
+}
+declare class IcebergRestCatalog implements IcebergCatalog {
+    private readonly url;
+    private readonly namespace;
+    private readonly table;
+    private readonly prefix;
+    private readonly token;
+    private readonly fetchFn;
+    constructor(options: IcebergRestCatalogOptions);
+    loadTable(store: ObjectStore): Promise<IcebergTable>;
+    listTables(): Promise<IcebergTableIdentifier[]>;
+    commitAppend(input: IcebergCommitInput): Promise<IcebergCommitResult>;
+    private requestJson;
+    private headers;
+    private tableUrl;
+    private namespaceTablesUrl;
+    private namespaceTableSegments;
+}
+declare function icebergRestCatalog(options: IcebergRestCatalogOptions): IcebergRestCatalog;
+declare class IcebergUnsupportedCatalog implements IcebergCatalog {
+    private readonly catalog;
+    private readonly namespace;
+    private readonly table;
+    constructor(catalog: string, namespace: string | string[], table: string);
+    loadTable(_store: ObjectStore): Promise<IcebergTable>;
+    listTables(): Promise<IcebergTableIdentifier[]>;
+    commitAppend(_input: IcebergCommitInput): Promise<IcebergCommitResult>;
+    private unsupported;
+}
+declare function icebergGlueCatalog(options: IcebergGlueCatalogOptions): IcebergCatalog;
+declare function icebergNessieCatalog(options: IcebergNessieCatalogOptions): IcebergCatalog;
+declare function loadIcebergTable(options: LoadIcebergTableOptions): Promise<IcebergTable>;
+declare function loadIcebergTableFromObjectStore(options: LoadIcebergTableFromObjectStoreOptions): Promise<IcebergTable>;
+declare function loadIcebergTableFromRest(options: LoadIcebergTableFromRestOptions): Promise<IcebergTable>;
+declare function applyIcebergDeletes(options: ApplyIcebergDeletesOptions): Row[];
+declare function scanPlannedIcebergRows(options: ScanPlannedIcebergRowsOptions): AsyncIterable<Row[]>;
+
+interface ReadParquetOptions {
+    /** Columns to project; all columns when omitted. */
+    columns?: string[];
+    rowStart?: number;
+    rowEnd?: number;
+}
+interface ReadParquetBatchOptions extends ReadParquetOptions {
+    batchSize?: number;
+    where?: Expr;
+}
+interface ParquetRowBatch {
+    rowOffset: number;
+    rows: Row[];
+}
+interface PlanParquetRowGroupsOptions {
+    where?: Expr;
+}
+interface PlannedParquetRowGroup {
+    index: number;
+    rowStart: number;
+    rowCount: number;
+    byteRange?: {
+        offset: number;
+        length: number;
+    };
+}
+interface ParquetRowGroupPlan {
+    rowGroups: PlannedParquetRowGroup[];
+    rowGroupRanges: {
+        start: number;
+        end: number;
+    }[];
+}
+type IcebergParquetDeleteFileContent = "position-delete" | "equality-delete" | "deletion-vector";
+interface IcebergParquetDeleteFile {
+    content: IcebergParquetDeleteFileContent;
+    path: string;
+}
+interface DecodedIcebergParquetDeletes {
+    positionDeletes?: {
+        path: string;
+        position: number;
+    }[];
+    equalityDeletes?: {
+        columns: string[];
+        row: Row;
+    }[];
+}
+interface WriteParquetOptions extends Omit<ParquetWriteOptions, "writer" | "columnData"> {
+    columnData: ColumnSource[];
+    contentType?: string;
+    writeMode?: "overwrite" | "create";
+}
+interface WriteParquetRowsOptions extends Omit<WriteParquetOptions, "columnData" | "schema"> {
+    rows: Row[];
+    partitionBy?: string[];
+    maxRowsPerFile?: number;
+    maxBytesPerFile?: number;
+    jobId?: string;
+    taskId?: string;
+    idempotencyKey?: string;
+    columnTypes?: Record<string, BasicType>;
+    validation?: InsertValidationRules;
+}
+interface InsertValidationRules {
+    required?: string[];
+    unique?: string[][];
+    ranges?: Record<string, {
+        min?: ComparableInsertValue;
+        max?: ComparableInsertValue;
+    }>;
+    enums?: Record<string, InsertValue[]>;
+}
+interface WritePartitionedParquetFile {
+    path: string;
+    byteSize: number;
+    contentHash: string;
+    etag?: string;
+    rowCount: number;
+    partitionValues: Record<string, string>;
+}
+interface WritePartitionedParquetResult {
+    files: WritePartitionedParquetFile[];
+}
+interface WritePartitionedParquetTaskOptions extends WriteParquetRowsOptions {
+    checkpoints: CheckpointAdapter;
+    taskId: string;
+    idempotencyKey: string;
+    nowMs?: number;
+    staleTimeoutMs?: number;
+    iceberg?: boolean;
+}
+interface WritePartitionedParquetTaskResult {
+    result: WritePartitionedParquetResult;
+    entries: OutputManifestEntry[];
+}
+interface CreateParquetTableAsQuery {
+    toArray(): Promise<Row[]>;
+}
+interface CreateParquetTableAsOptions extends Omit<WritePartitionedParquetTaskOptions, "rows" | "jobId" | "taskId" | "idempotencyKey"> {
+    query: CreateParquetTableAsQuery;
+    jobId: string;
+    planFingerprint: string;
+    taskId?: string;
+    idempotencyKey: string;
+}
+interface CreateParquetTableAsResult extends WritePartitionedParquetTaskResult {
+    manifest: OutputManifest;
+    rowsRead: number;
+}
+interface PartitionedParquetOutputEntryOptions {
+    taskId: string | ((file: WritePartitionedParquetFile, index: number) => string);
+    iceberg?: boolean;
+}
+interface ParquetLakeConfig extends Omit<LakeConfig, "scanner"> {
+    batchSize?: number;
+    metadataCache?: CacheAdapter<ParquetMetadata>;
+}
+type ParquetMetadata = Awaited<ReturnType<typeof parquetMetadataAsync>>;
+interface StoreAsyncBuffer {
+    byteLength: number;
+    etag?: string;
+    slice(start: number, end?: number): Promise<ArrayBuffer>;
+}
+/**
+ * Bridge an ObjectStore path to hyparquet's AsyncBuffer (length + ranged slice).
+ */
+declare function asyncBufferFromStore(store: ObjectStore, path: string, options?: ScanOptions | undefined): Promise<StoreAsyncBuffer>;
+/**
+ * Read rows from a Parquet object. Early scaffold: full planner-driven
+ * row-group pruning and batch streaming land in phase 1-2 (see BUILD_PLAN.md).
+ */
+declare function readParquetObjects(store: ObjectStore, path: string, options?: ReadParquetOptions): Promise<Record<string, unknown>[]>;
+declare function readParquetObjectBatches(store: ObjectStore, path: string, options?: ReadParquetBatchOptions): AsyncIterable<ParquetRowBatch>;
+/** Read Parquet footer metadata (row groups, schema, stats). */
+declare function readParquetMetadata(store: ObjectStore, path: string): Promise<hyparquet_src_types_js.FileMetaData>;
+declare function planRowGroups(store: ObjectStore, path: string, options?: PlanParquetRowGroupsOptions): Promise<ParquetRowGroupPlan>;
+declare function readIcebergParquetDeletes(store: ObjectStore, deleteFile: IcebergParquetDeleteFile): Promise<DecodedIcebergParquetDeletes>;
+declare function writeParquet(store: ObjectStore, path: string, options: WriteParquetOptions): Promise<{
+    path: string;
+    byteSize: number;
+    etag?: string;
+}>;
+declare function writePartitionedParquet(store: ObjectStore, prefix: string, options: WriteParquetRowsOptions): Promise<WritePartitionedParquetResult>;
+declare function writePartitionedParquetTask(store: ObjectStore, prefix: string, options: WritePartitionedParquetTaskOptions): Promise<WritePartitionedParquetTaskResult>;
+declare function createParquetTableAs(store: ObjectStore, prefix: string, options: CreateParquetTableAsOptions): Promise<CreateParquetTableAsResult>;
+declare function partitionedParquetOutputEntries(result: WritePartitionedParquetResult, options: PartitionedParquetOutputEntryOptions): OutputManifestEntry[];
+declare class ParquetScanAdapter implements ScanAdapter {
+    private readonly store;
+    private readonly defaultBatchSize;
+    private readonly metadataCache;
+    constructor(store: ObjectStore, options?: {
+        batchSize?: number;
+        metadataCache?: CacheAdapter<ParquetMetadata>;
+    });
+    scan(path: string, options: ScanOptions): AsyncIterable<Row[]>;
+    planTask(path: string, options: ScanTaskPlanOptions): Promise<ScanTaskPlan>;
+    private metadata;
+}
+declare function planRowGroupsFromMetadata(metadata: ParquetMetadata, where: Expr | undefined): ParquetRowGroupPlan;
+declare function rejectUnsupportedParquetSchema(metadata: ParquetMetadata): void;
+type InsertValue = string | number | boolean | bigint | null;
+type ComparableInsertValue = string | number | bigint;
+/** @internal Exposed for pruning tests; not part of the stable public API. */
+declare function rowGroupMayMatch(rowGroup: RowGroup, expr: Expr | undefined): boolean;
+declare function parquetScanner(store: ObjectStore, options?: {
+    batchSize?: number;
+    metadataCache?: CacheAdapter<ParquetMetadata>;
+}): ScanAdapter;
+declare function createParquetLake(config: ParquetLakeConfig): Lake;
+
+interface LoadIcebergEngineTableOptions extends LoadIcebergTableOptions {
+    format: "iceberg";
+}
+interface LoadParquetEngineTableOptions {
+    format: "parquet";
+    store: ObjectStore;
+    path: string;
+}
+type LoadTableOptions = LoadIcebergEngineTableOptions | LoadParquetEngineTableOptions;
+interface IcebergEngineTable {
+    format: "iceberg";
+    store: ObjectStore;
+    table: IcebergTable;
+}
+interface ParquetEngineTable {
+    format: "parquet";
+    store: ObjectStore;
+    path: string;
+}
+type EngineTable = IcebergEngineTable | ParquetEngineTable;
+interface IcebergEnginePlan {
+    format: "iceberg";
+    store: ObjectStore;
+    table: IcebergTable;
+    plan: IcebergPlan;
+    options: PlanIcebergFilesOptions;
+}
+interface ParquetEnginePlan {
+    format: "parquet";
+    store: ObjectStore;
+    files: {
+        path: string;
+    }[];
+}
+type EngineFilePlan = IcebergEnginePlan | ParquetEnginePlan;
+interface ScanEngineOptions extends ObjectStoreReadControls {
+    batchSize?: number;
+}
+type ScanBatch = Row[];
+declare function loadTable(options: LoadTableOptions): Promise<EngineTable>;
+declare function planFiles(table: IcebergEngineTable, options?: PlanIcebergFilesOptions): IcebergEnginePlan;
+declare function planFiles(table: ParquetEngineTable): ParquetEnginePlan;
+declare function planFiles(table: EngineTable, options?: PlanIcebergFilesOptions): EngineFilePlan;
+declare function scanBatches(plan: EngineFilePlan, options?: ScanEngineOptions): AsyncIterable<ScanBatch>;
+declare function scanRows(plan: EngineFilePlan, options?: ScanEngineOptions): AsyncIterable<Row>;
+
+export { type AggregateExpr, type AggregateGroupSnapshot, type AggregateOp, type AggregateOperatorState, type AggregateOptions, type AggregateResult, type AggregateSnapshotValue, type AggregateSpec, type AggregateStateSnapshot, AggregationBuilder, type ApplyIcebergDeletesOptions, type BBoxIndex, type BetweenExpr, type Bookmark, type BookmarkInit, type BookmarkPosition, type BookmarkQuery, type BroadcastJoinOptions, type CacheAdapter, CacheApiCache, type CacheApiCacheOptions, type CacheEntry, type CallExpr, type CheckpointAdapter, type CheckpointStore, type Clock, type ColumnExpr, type ColumnInput, type CompareExpr, type CompareOp, type ConditionalObjectStore, type ConditionalPutOptions, type CreateParquetTableAsOptions, type CreateParquetTableAsQuery, type CreateParquetTableAsResult, type CsvStreamOptions, type DecodedIcebergDeletes, type DecodedIcebergParquetDeletes, ERROR_CODES, type EngineFilePlan, type EngineTable, type ErrorDetails, type ExplainJson, type ExplainResult, type Expr, type IcebergAppendFile, type IcebergAppendOptions, type IcebergAppendOutputManifestOptions, type IcebergAppendResult, type IcebergCatalog, type IcebergCommitCatalog, type IcebergCommitInput, type IcebergCommitResult, type IcebergDeleteFile, type IcebergDeletionVector, type IcebergEnginePlan, type IcebergEngineTable, type IcebergEqualityDelete, type IcebergField, type IcebergGlueCatalogOptions, type IcebergNessieCatalogOptions, type IcebergParquetDeleteFile, type IcebergParquetDeleteFileContent, type IcebergPartitionField, type IcebergPartitionSpec, type IcebergPlan, type IcebergPositionDelete, type IcebergReadMode, IcebergRestCatalog, type IcebergRestCatalogOptions, type IcebergRowBatch, type IcebergSortOrder, IcebergTable, type IcebergTableIdentifier, IcebergUnsupportedCatalog, type IdGenerator, type InExpr, type IndexPruneResult, type IndexValue, type InsertValidationRules, type JoinType, type JsonExpr, type JsonOrderByTerm, type JsonQueryV1, LaQLError, type LaQLErrorCode, Lake, type LakeConfig, type LikeExpr, type ListOptions, type LiteralExpr, type LoadIcebergEngineTableOptions, type LoadIcebergTableFromObjectStoreOptions, type LoadIcebergTableFromRestOptions, type LoadIcebergTableOptions, type LoadParquetEngineTableOptions, type LoadTableOptions, type LockAdapter, type LogHook, type LogicalExpr, type LookupJoinFunction, type LookupJoinOptions, type Manifest, type ManifestDeleteFile, type ManifestFile, MemoryCache, MemoryCheckpointAdapter, MemoryObjectStore, MemorySpillAdapter, type MemorySpillAdapterOptions, type MetadataFile, type MetricsHook, type MinMaxColumnIndex, type NotExpr, type NullCheckExpr, type ObjectHead, type ObjectInfo, type ObjectStore, ObjectStoreIcebergCommitCatalog, type ObjectStoreReadControls, type OperatorSnapshotValue, type OrderByTerm, type OutputManifest, type OutputManifestEntry, PACKAGE, type ParquetEnginePlan, type ParquetEngineTable, type ParquetLakeConfig, type ParquetMetadata, type ParquetRowBatch, type ParquetRowGroupPlan, ParquetScanAdapter, type PartitionedParquetOutputEntryOptions, type PathQueryInit, type PlanIcebergFilesOptions, type PlanParquetRowGroupsOptions, type PlannedIcebergFile, type PlannedParquetRowGroup, type PredicatePlan, type PredicatePlanOptions, type ProjectIcebergRowOptions, type PutOptions, type QueryBudget, QueryBuilder, type QueryPolicy, type QueryPolicyContext, QueryResult, type QueryRunOptions, type QueryStats, type QueueAdapter, type ReadParquetBatchOptions, type ReadParquetOptions, type ResumableBatchOptions, ResumedQuery, type Row, type RuntimeSubstrate, type Scalar, type ScanAdapter, type ScanBatch, type ScanEngineOptions, type ScanOptions, type ScanPlannedIcebergRowsOptions, type ScanTaskPlan, type ScanTaskPlanOptions, type SidecarFileIndex, type SliceOptions, type SliceResult, type Snapshot, type SortOperatorState, type SortOptions, type SortResult, type SortRunState, type SpillAdapter, type SpillRef, type SpillUsage, type SqlBoolean, type TaskCheckpoint, type TaskInput, type TaskManifest, type TaskManifestTask, type TaskState, type TaskTransitionInput, type TopKOperatorState, type TopKOptions, type TopKResult, type ValueInput, type WriteParquetOptions, type WriteParquetRowsOptions, type WritePartitionedParquetFile, type WritePartitionedParquetResult, type WritePartitionedParquetTaskOptions, type WritePartitionedParquetTaskResult, advanceTaskCheckpoint, and, applyIcebergDeletes, assertBookmarkMatches, asyncBufferFromStore, bboxMayIntersect, between, broadcastJoin, buildBBoxIndex, buildMinMaxIndex, cacheApiCache, classifyPredicate, col, createBookmark, createParquetLake as createLake, createOutputManifest, createOutputManifestFromCheckpoints, createParquetLake, createParquetTableAs, createTaskManifest, deserializeAggregateOperatorState, deserializeSortOperatorState, deserializeTopKOperatorState, encodeJsonLine, eq, evaluate, fingerprint, fn, gt, gte, icebergGlueCatalog, icebergNessieCatalog, icebergRestCatalog, ilike, isIn, isLaQLError, isNotNull, isNull, jsonSafeValue, like, lit, loadIcebergTable, loadIcebergTableFromObjectStore, loadIcebergTableFromRest, loadTable, lookupJoin, lt, lte, matches, memoryCache, memoryCheckpointAdapter, memorySpillAdapter, memoryStore, ne, not, notIn, or, parquetScanner, parseHivePartitions, parseJsonQuery, partitionedParquetOutputEntries, planFiles, planRowGroups, planRowGroupsFromMetadata, pruneFilesWithIndex, readControlSignal, readIcebergParquetDeletes, readOutputManifest, readParquetMetadata, readParquetObjectBatches, readParquetObjects, rejectUnsupportedParquetSchema, rowGroupMayMatch, scanBatches, scanPlannedIcebergRows, scanRows, serializeAggregateOperatorState, serializeSortOperatorState, serializeTopKOperatorState, signPaginationToken, stableStringify, throwIfAborted, transitionTaskCheckpoint, verifyPaginationToken, withObjectStoreReadControls, writeOutputManifest, writeParquet, writePartitionedParquet, writePartitionedParquetTask };