@query-farm/vgi 0.6.0

package/dist/client-entry.d.ts

@@ -0,0 +1,11 @@
+export { VgiClient, VgiClientError } from "./client/client.js";
+export type { VgiClientOptions, TableFunctionOptions, ScalarFunctionOptions, TableInOutFunctionOptions, OnCreateConflict, CatalogFunctionType, } from "./client/types.js";
+export { Arguments } from "./arguments/arguments.js";
+export { type ArgumentSpec, argumentSpecsToSchema, schemaToArgumentSpecs, } from "./arguments/argument-spec.js";
+export { FunctionType, FunctionStability, NullHandling, OrderPreservation, OrderDependence, DistinctDependence, TableInOutPhase, } from "./types.js";
+export type { BindRequest, BindResponse, InitRequest, GlobalInitResponse, TableCardinality, } from "./protocol/types.js";
+export { type SchemaInfo, encodeSchemaInfo, decodeSchemaInfo, type TableInfo, encodeTableInfo, decodeTableInfo, type ViewInfo, encodeViewInfo, decodeViewInfo, type FunctionInfo, encodeFunctionInfo, decodeFunctionInfo, type MacroInfo, encodeMacroInfo, decodeMacroInfo, type CatalogAttachResult, type AttachOpaqueData, type TransactionOpaqueData, } from "./catalog/interface.js";
+export { VgiError, RowCountMismatchError, FunctionNotFoundError, CatalogReadOnlyError, CatalogNotFoundError, CatalogAlreadyExistsError, ArgumentValidationError, NoCatalogError, } from "./errors.js";
+export { iterRows, batchFromRows, batchFromColumns, emptyBatch, filterBatch, projectSchema, projectBatch, batchToScalarDict, safeNumber, serializeSchema, deserializeSchema, serializeBatch, deserializeBatch, } from "./util/arrow/index.js";
+export { toUint8Array } from "./util/bytes.js";
+export type { RpcClient, StreamSession, LogMessage } from "@query-farm/vgi-rpc";

package/dist/client-entry.js

@@ -0,0 +1,48 @@
+export {
+  toUint8Array,
+  serializeSchema,
+  serializeBatch,
+  schemaToArgumentSpecs,
+  safeNumber,
+  projectSchema,
+  projectBatch,
+  iterRows,
+  filterBatch,
+  encodeViewInfo,
+  encodeTableInfo,
+  encodeSchemaInfo,
+  encodeMacroInfo,
+  encodeFunctionInfo,
+  emptyBatch,
+  deserializeSchema,
+  deserializeBatch,
+  decodeViewInfo,
+  decodeTableInfo,
+  decodeSchemaInfo,
+  decodeMacroInfo,
+  decodeFunctionInfo,
+  batchToScalarDict,
+  batchFromRows,
+  batchFromColumns,
+  argumentSpecsToSchema,
+  VgiError,
+  VgiClientError,
+  VgiClient,
+  TableInOutPhase,
+  RowCountMismatchError,
+  OrderPreservation,
+  OrderDependence,
+  NullHandling,
+  NoCatalogError,
+  FunctionType,
+  FunctionStability,
+  FunctionNotFoundError,
+  DistinctDependence,
+  CatalogReadOnlyError,
+  CatalogNotFoundError,
+  CatalogAlreadyExistsError,
+  Arguments,
+  ArgumentValidationError
+};
+
+//# debugId=C4422E46DEACD50764756E2164756E21

package/dist/client-entry.js.map

@@ -0,0 +1,9 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [
+  ],
+  "mappings": "",
+  "debugId": "C4422E46DEACD50764756E2164756E21",
+  "names": []
+}

package/dist/codec/asd.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Generic ArrowSerializableDataclass (ASD) codec.
+ *
+ * Bridges between typed TS objects (snake_case, matching vgi-python dataclass
+ * field names) and Arrow IPC bytes (single-row batch with the dataclass'
+ * ARROW_SCHEMA). Used by the generated vgi-client.ts encode<X>/decode<X>
+ * wrappers to make the typed client interfaces honest at the wire boundary.
+ *
+ * Encoding delegates to the facade's `batchFromRows` (which handles the
+ * complex types — Decimal/BigInt/List/Map/Struct/Dictionary — uniformly
+ * across both arrow-js and flechette backends). Decoding pulls each field's
+ * value with `batchToScalarDict`, then runs `normalizeValue` to convert
+ * Arrow representations (MapRow, BigInt, etc.) back into plain JS shapes.
+ */
+import { type VgiSchema } from "../arrow/index.js";
+/**
+ * Encode a typed object as a single-row Arrow IPC stream using `schema`.
+ * Matches Python's `ArrowSerializableDataclass.serialize_to_bytes()`.
+ */
+export declare function encodeASD(schema: VgiSchema, obj: Record<string, any>): Uint8Array;
+/**
+ * Decode a single-row Arrow IPC stream into a typed object using `schema`.
+ * Matches Python's `ArrowSerializableDataclass.deserialize_from_bytes()`.
+ */
+export declare function decodeASD<T>(schema: VgiSchema, bytes: Uint8Array): T;

package/dist/crypto.d.ts

@@ -0,0 +1,36 @@
+import type { AuthContext } from "@query-farm/vgi-rpc";
+export declare const ATTACH_ENVELOPE_VERSION = 2;
+export declare const TRANSACTION_ENVELOPE_VERSION = 2;
+/** Width of the framework UUID prepended to every attach plaintext. */
+export declare const ATTACH_UUID_LEN = 16;
+/**
+ * Thrown when an envelope cannot be opened — wrong principal, wrong parent
+ * attach, tampered, malformed, or simply unknown. Every failure mode maps to
+ * this single error so a probing caller cannot distinguish them.
+ */
+export declare class OpaqueDataRejectedError extends Error {
+    constructor(field?: string);
+}
+/**
+ * Build the identity portion of an opaque-data AAD. Unauthenticated requests
+ * get a fixed anonymous tail, so an anonymous caller cannot open an envelope
+ * sealed for a real principal.
+ */
+export declare function identityTail(auth: AuthContext | undefined): Uint8Array;
+/** AAD for an `attach_opaque_data` envelope: prefix + caller identity. */
+export declare function attachAad(auth: AuthContext | undefined): Uint8Array;
+/**
+ * AAD for a `transaction_opaque_data` envelope. Binds both the caller identity
+ * and the parent attach envelope, so a transaction value minted under one
+ * attach cannot be replayed against a different attach even by the same
+ * principal.
+ */
+export declare function transactionAad(auth: AuthContext | undefined, attachEnvelope: Uint8Array): Uint8Array;
+/** Seal `payload` into an AEAD envelope: version || nonce || ciphertext+tag. */
+export declare function sealBytes(payload: Uint8Array, key: Uint8Array, aad: Uint8Array, version: number): Promise<Uint8Array>;
+/**
+ * Open and verify an envelope produced by {@link sealBytes}. Every failure
+ * mode — malformed, wrong version, tampered, wrong key, wrong AAD
+ * (cross-principal / cross-attach replay) — throws {@link OpaqueDataRejectedError}.
+ */
+export declare function openBytes(token: Uint8Array, key: Uint8Array, aad: Uint8Array, version: number, field?: string): Promise<Uint8Array>;

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+export declare class VgiError extends Error {
+    constructor(message: string);
+}
+export declare class RowCountMismatchError extends VgiError {
+    constructor(expected: number, actual: number);
+}
+export declare class FunctionNotFoundError extends VgiError {
+    constructor(name: string, available?: string[]);
+}
+export declare class CatalogReadOnlyError extends VgiError {
+    constructor(operation: string);
+}
+export declare class CatalogNotFoundError extends VgiError {
+    constructor(entity: string, name: string);
+}
+export declare class CatalogAlreadyExistsError extends VgiError {
+    constructor(entity: string, name: string);
+}
+export declare class ArgumentValidationError extends VgiError {
+    constructor(message: string);
+}
+export declare class NoCatalogError extends VgiError {
+    constructor();
+}

package/dist/filter-pushdown/collector.d.ts

@@ -0,0 +1,32 @@
+import { type VgiBatch, type VgiSchema } from "../arrow/index.js";
+import type { OutputCollector } from "@query-farm/vgi-rpc";
+import { PushdownFilters } from "./evaluate.js";
+/**
+ * Format pushdown filters as a human-readable SQL-like string.
+ * Returns "(none)" when no filters exist.
+ */
+export declare function formatPushedFilters(filters: PushdownFilters | undefined): string;
+/**
+ * Format pushdown filters using Python-style `repr()` — e.g.
+ * `PushdownFilters([ConstantFilter(n < 4999)])`. Matches vgi-python's
+ * `_format_pushed_filters_safe` output so tests that pattern-match the
+ * repr (e.g. `dynamic_filter` checking for `ConstantFilter(n <`) work
+ * identically across workers.
+ */
+export declare function reprPushedFilters(filters: PushdownFilters | undefined): string;
+/**
+ * Wraps an OutputCollector to automatically apply pushdown filters
+ * to every emitted batch.
+ */
+export declare class FilteringOutputCollector {
+    private inner;
+    private filters;
+    constructor(inner: OutputCollector, filters: PushdownFilters);
+    get outputSchema(): VgiSchema;
+    get finished(): boolean;
+    emit(batch: VgiBatch, metadata?: Map<string, string>): void;
+    emit(columns: Record<string, any[]>): void;
+    emitRow(values: Record<string, any>): void;
+    finish(): void;
+    clientLog(level: string, message: string, extra?: Record<string, string>): void;
+}

package/dist/filter-pushdown/deserialize.d.ts

@@ -0,0 +1,16 @@
+import { type VgiBatch } from "../arrow/index.js";
+import { PushdownFilters } from "./evaluate.js";
+/**
+ * Build a getJoinKeysColumn lookup from an InitRequest's `joinKeys` batches.
+ * Each batch typically has a single column whose name is the join-keys column
+ * referenced by `spec.keys_column` on a join_keys filter.
+ */
+export declare function buildJoinKeysLookup(joinKeyBatches: VgiBatch[]): (columnName: string) => any[] | null;
+/**
+ * Deserialize pushdown filters from an Arrow RecordBatch.
+ *
+ * Wire format:
+ * - Column 0: UTF8 — JSON array of filter specs. Field metadata: vgi_filter_version: "1"
+ * - Columns 1+: Scalar values referenced by value_ref → column N+1
+ */
+export declare function deserializeFilters(batch: VgiBatch, getJoinKeysColumn?: (columnName: string) => any[] | null): PushdownFilters;

package/dist/filter-pushdown/evaluate.d.ts

@@ -0,0 +1,51 @@
+import { type VgiBatch } from "../arrow/index.js";
+import { type Filter } from "./types.js";
+export declare class PushdownFilters {
+    readonly filters: Filter[];
+    readonly version: string;
+    constructor(filters: Filter[], version: string);
+    /** Convert filters to a human-readable SQL-like string. */
+    toSql(): string;
+    /** Evaluate filters against a batch, returning a Uint8Array mask (0=fail, 1=pass). */
+    evaluate(batch: VgiBatch): Uint8Array;
+    /** Apply filters to a batch, returning only passing rows. */
+    apply(batch: VgiBatch): VgiBatch;
+    /**
+     * The set of column names referenced by the pushed-down filters, sorted
+     * ascending. Descends one level into AndFilter children (DuckDB pushes
+     * `col IN (...) AND col>=min` as a single AndFilter), consistent with
+     * `getColumnValues` / `hasFilterForColumn`. Mirrors the cross-language
+     * `filtered_columns` accessor (vgi-python / vgi-go / vgi-rust).
+     */
+    filteredColumns(): string[];
+    /**
+     * Whether any pushed-down filter references `columnName`. Mirrors the
+     * cross-language `has_filter_for_column` accessor.
+     */
+    hasFilterForColumn(columnName: string): boolean;
+    /**
+     * Discrete values a column could take, from equality (`=`) or `IN` filters.
+     * Useful for partition pruning (resolve the key set up front, fetch only
+     * those keys). Returns null when the predicate is not enumerable — no
+     * filter, a bare range, or an OR with a non-discrete branch.
+     *
+     * Mirrors vgi-python's `PushdownFilters.get_column_values`: descends one
+     * level into an AndFilter (DuckDB pushes `col IN (...) AND col>=min AND
+     * col<=max` as a single AndFilter from a semi-join), and unions OR branches
+     * only when every branch pins the column to discrete values.
+     */
+    getColumnValues(columnName: string): any[] | null;
+    /**
+     * Union of discrete values for `columnName` across all OR branches, iff every
+     * child constrains it to discrete values (`=` or `IN`); otherwise null (the
+     * column could take any value through a non-discrete branch). Returning one
+     * branch's values would be an unsafe subset.
+     */
+    private orDiscreteValues;
+    /**
+     * Collect filters for a column from the top level and direct AND children
+     * (one level of descent, consistent with the Python accessor). Deeply nested
+     * AND/AND is not traversed.
+     */
+    private collectColumnFilters;
+}

package/dist/filter-pushdown/index.d.ts

@@ -0,0 +1,4 @@
+export { ComparisonOp, type AndFilter, type ConstantFilter, type ExpressionFilter, type ExprNode, type Filter, type InFilter, type IsNotNullFilter, type IsNullFilter, type OrFilter, type StructFilter, } from "./types.js";
+export { PushdownFilters } from "./evaluate.js";
+export { buildJoinKeysLookup, deserializeFilters } from "./deserialize.js";
+export { FilteringOutputCollector, formatPushedFilters, reprPushedFilters, } from "./collector.js";

package/dist/filter-pushdown/types.d.ts

@@ -0,0 +1,84 @@
+export declare enum ComparisonOp {
+    EQ = "eq",
+    NE = "ne",
+    GT = "gt",
+    GE = "ge",
+    LT = "lt",
+    LE = "le"
+}
+export interface ConstantFilter {
+    type: "constant";
+    columnName: string;
+    columnIndex: number;
+    op: ComparisonOp;
+    value: any;
+}
+export interface IsNullFilter {
+    type: "is_null";
+    columnName: string;
+    columnIndex: number;
+}
+export interface IsNotNullFilter {
+    type: "is_not_null";
+    columnName: string;
+    columnIndex: number;
+}
+export interface InFilter {
+    type: "in";
+    columnName: string;
+    columnIndex: number;
+    values: Set<any>;
+}
+export interface AndFilter {
+    type: "and";
+    columnName: string;
+    columnIndex: number;
+    children: Filter[];
+}
+export interface OrFilter {
+    type: "or";
+    columnName: string;
+    columnIndex: number;
+    children: Filter[];
+}
+export interface StructFilter {
+    type: "struct";
+    columnName: string;
+    columnIndex: number;
+    childIndex: number;
+    childName: string;
+    childFilter: Filter;
+}
+export type Filter = ConstantFilter | IsNullFilter | IsNotNullFilter | InFilter | AndFilter | OrFilter | StructFilter | ExpressionFilter;
+/**
+ * Expression-tree filter. The expr is a parsed AST; evaluation matches
+ * DuckDB's semantics for the function names the table function advertises in
+ * `supportedExpressionFilters` (e.g. list_contains, starts_with, contains,
+ * &&/st_intersects_extent for spatial).
+ */
+export interface ExpressionFilter {
+    type: "expression";
+    columnName: string;
+    columnIndex: number;
+    expr: ExprNode;
+}
+export type ExprNode = {
+    expr_type: "column_ref";
+    index: number;
+} | {
+    expr_type: "constant";
+    value: any;
+} | {
+    expr_type: "function";
+    function_name: string;
+    children: ExprNode[];
+} | {
+    expr_type: "comparison";
+    op: ComparisonOp;
+    left: ExprNode;
+    right: ExprNode;
+} | {
+    expr_type: "conjunction";
+    conjunction_type: "and" | "or";
+    children: ExprNode[];
+};

package/dist/functions/aggregate.d.ts

@@ -0,0 +1,129 @@
+import { type VgiSchema, type VgiBatch, type VgiDataType } from "../arrow/index.js";
+import type { Arguments } from "../arguments/arguments.js";
+import type { VgiFunction } from "./types.js";
+import type { FunctionExample } from "./types.js";
+export declare const GROUP_COLUMN_NAME = "__vgi_group_id";
+export interface AggregateBindParams<TArgs = Record<string, any>> {
+    args: TArgs;
+    arguments: Arguments;
+    inputSchema: VgiSchema | null;
+    settings: Record<string, any>;
+    secrets: Record<string, Record<string, any>>;
+}
+export interface AggregateUpdateParams<TArgs = Record<string, any>, TState = any> {
+    states: Map<bigint, TState>;
+    groupIds: bigint[];
+    columns: any[];
+    args: TArgs;
+    /**
+     * Get-or-initialize accessor for per-group state. Call this inside the loop
+     * only when the row actually contributes to the aggregate — skipping it
+     * (e.g. on NULL input under NullHandling.DEFAULT) leaves `states` without
+     * an entry for the group, so finalize() can return SQL NULL for that
+     * group (matches vgi-python's "state absent = NULL" semantics for
+     * SUM/AVG/MIN/MAX over zero non-null rows).
+     */
+    ensureState: (gid: bigint) => TState;
+}
+export interface AggregateFinalizeParams<TArgs = Record<string, any>, TState = any> {
+    groupIds: bigint[];
+    states: Map<bigint, TState | null>;
+    outputSchema: VgiSchema;
+    args: TArgs;
+}
+export interface AggregateFunctionConfig<TArgs = Record<string, any>, TState = any> {
+    name: string;
+    description?: string;
+    /**
+     * Map of positional argument name → Arrow type. Passed through to DuckDB
+     * function registration. Use `null` (untyped) for varargs placeholders.
+     */
+    args?: Record<string, VgiDataType>;
+    /**
+     * Names of args that accept a variable number of column arguments. DuckDB
+     * treats these as varargs of the declared Arrow type; at call time the
+     * function may receive 1..N columns of that type. update() sees all of
+     * them as consecutive entries in `columns`.
+     */
+    varargs?: string[];
+    /**
+     * Names of args whose value is constant (known at bind time) and must be
+     * folded away by DuckDB before reaching update(). The value arrives in
+     * `bindParams.args[name]`; it is NOT passed as an input column in the
+     * update batch. Use for aggregates parameterized by a literal (e.g.
+     * percentile=0.5 in vgi_percentile).
+     */
+    constParams?: string[];
+    /**
+     * Arrow type of the aggregate's output (one value per group). DuckDB uses
+     * this to build the result column type at bind time. May be overridden
+     * at bind time by `onBind` (returning a different Arrow type) for
+     * aggregates whose return type depends on the input column type
+     * (e.g. vgi_generic_sum: BIGINT input → BIGINT output, DOUBLE → DOUBLE).
+     */
+    outputType: VgiDataType;
+    /**
+     * Optional bind-time hook for dynamic output types. Receives the bind
+     * parameters (including input_schema) and returns the Arrow type to
+     * advertise for this invocation. Defaults to returning `config.outputType`.
+     */
+    onBind?: (params: AggregateBindParams<TArgs>) => VgiDataType | Promise<VgiDataType>;
+    /** Optional per-arg default values (positional only here). */
+    argDefaults?: Record<string, any>;
+    initialState: (params: AggregateBindParams<TArgs>) => TState;
+    /**
+     * Fold a batch of input rows into the provided per-group state map.
+     * Implementations mutate `states` in place. `groupIds[i]` identifies which
+     * group row i belongs to; `columns[k][i]` is the value for the kth declared
+     * column argument at row i.
+     */
+    update: (params: AggregateUpdateParams<TArgs, TState>) => void;
+    combine: (source: TState, target: TState, params: AggregateBindParams<TArgs>) => TState;
+    /** Must return a single-column RecordBatch with `groupIds.length` rows. */
+    finalize: (params: AggregateFinalizeParams<TArgs, TState>) => VgiBatch;
+    examples?: FunctionExample[];
+    categories?: string[];
+    /** Arbitrary function-level tags surfaced into duckdb_functions().tags. */
+    tags?: Record<string, string>;
+    nullHandling?: "DEFAULT" | "SPECIAL";
+    /**
+     * DuckDB secret types this aggregate needs. Advertised on the catalog's
+     * `required_secrets` so the C++ extension pre-resolves matching secrets and
+     * delivers their VALUES on the aggregate_bind request (keyed by secret name).
+     * The secret is read at bind time only — update/combine/finalize receive an
+     * empty ResolvedSecrets. Mirrors vgi-python's `Secret()` annotation on an
+     * aggregate `on_bind`.
+     */
+    requiredSecrets?: string[];
+}
+type StateMap = Map<bigint, any>;
+interface ExecEntry {
+    states: StateMap;
+    bindArgs: Arguments;
+    bindParams: AggregateBindParams<any>;
+    loaded: Set<bigint>;
+}
+/**
+ * Fetch the execution context — bind args/params + states for requested gids.
+ * On cache miss, tries to reconstruct from on-disk files written by a
+ * sibling worker. Returns undefined if the exec never existed anywhere.
+ * `requestedGids` (optional) tells us which group states to pre-load.
+ */
+export declare function getExecutionState(executionId: Uint8Array, requestedGids?: Iterable<bigint>): ExecEntry | undefined;
+export declare function setExecutionState(executionId: Uint8Array, entry: Omit<ExecEntry, "loaded">): void;
+/**
+ * Persist the given group states to disk so sibling workers can pick them up.
+ * Deletes the on-disk entry when the in-memory state was removed (gid no
+ * longer present in states map).
+ */
+export declare function persistGroupStates(executionId: Uint8Array, gids: Iterable<bigint>): void;
+export declare function deleteExecutionState(executionId: Uint8Array): void;
+/**
+ * Declare an aggregate function. The returned VgiFunction has `kind:
+ * "aggregate"` plus a `config` handle the dispatch layer uses to drive the
+ * aggregate_* RPCs; the scalar/table-function code paths ignore it.
+ */
+export declare function defineAggregate<TArgs = Record<string, any>, TState = any>(config: AggregateFunctionConfig<TArgs, TState>): VgiFunction & {
+    aggregateConfig: AggregateFunctionConfig<TArgs, TState>;
+};
+export {};

package/dist/functions/copy-from.d.ts

@@ -0,0 +1,81 @@
+import { type VgiSchema, type VgiDataType } from "../arrow/index.js";
+import type { OutputCollector } from "@query-farm/vgi-rpc";
+import type { BindRequest } from "../protocol/types.js";
+import type { VgiFunction, FunctionExample } from "./types.js";
+import type { CopySecretLookup } from "./copy-to.js";
+import type { TableProcessParams } from "./table.js";
+/** Declaration of a single COPY option (a named function argument). */
+export interface CopyFromOption {
+    /** Arrow type of the option value (e.g. `utf8()`, `int64()`). */
+    type: VgiDataType;
+    /** Per-option description, surfaced by `vgi_copy_formats()`. */
+    doc?: string;
+    /**
+     * Default value. When omitted the option is REQUIRED — the worker throws a
+     * clear error at COPY bind if the user does not supply it. Mirrors
+     * vgi-python's `Arg(..., default=...)` (no default => required).
+     */
+    default?: unknown;
+    /**
+     * Optional allowed value set, validated worker-side at bind. Mirrors
+     * vgi-python's `Arg(..., choices=[...])`.
+     */
+    choices?: unknown[];
+}
+export interface CopyFromReadParams<TArgs = Record<string, unknown>> {
+    /** Source path from the `COPY ... FROM 'path'` statement. */
+    path: string;
+    /** Parsed COPY options (defaults applied). */
+    options: TArgs;
+    /**
+     * The COPY target's schema. Every emitted batch must have this exact schema
+     * (names + types, in order) — DuckDB inserts no cast before the INSERT.
+     */
+    expectedSchema: VgiSchema;
+    /** Full process parameters (settings, secrets, storage). */
+    processParams: TableProcessParams<TArgs>;
+    /** Collector to emit batches / log. `finish()` is called for you. */
+    out: OutputCollector;
+}
+export interface CopyFromFunctionConfig<TArgs = Record<string, unknown>> {
+    /** Handler name (the function's registered name; `Meta.name`). */
+    name: string;
+    /** SQL `FORMAT` identifier users type, e.g. `COPY t FROM 'x' (FORMAT myfmt)`. */
+    format: string;
+    /** Function description (intrinsic documentation; `Meta.description`). */
+    description?: string;
+    /** Optional free-text comment surfaced by `vgi_copy_formats()`. */
+    comment?: string | null;
+    /** Reserved for a future `COPY ... TO`; only `"from"` is supported today. */
+    direction?: string;
+    /** COPY options, keyed by option name. The `file_path` is NOT an option. */
+    options?: Record<string, CopyFromOption>;
+    categories?: string[];
+    tags?: Record<string, string>;
+    examples?: FunctionExample[];
+    requiredSettings?: string[];
+    requiredSecrets?: string[];
+    /**
+     * Optional secret-bind hook: forward CREATE SECRET credentials for
+     * secret-backed cloud sources (S3/GCS/HTTP/…). Called during bind (only on the
+     * first pass); return the secrets to resolve — typically scoped by the source
+     * `path`. The framework's two-phase secret bind resolves each lookup from the
+     * caller's SecretManager and surfaces the resolved values on
+     * `processParams.secrets` at `read` time. Mirrors vgi-python's
+     * `CopyFromFunction.on_secrets`.
+     */
+    onSecrets?: (params: {
+        options: TArgs;
+        path: string;
+        bindCall: BindRequest;
+    }) => CopySecretLookup[] | void;
+    /** Parse `path` and emit Arrow batches matching `expectedSchema`. */
+    read: (params: CopyFromReadParams<TArgs>) => void | Promise<void>;
+}
+/**
+ * Define a custom `COPY ... FROM` format reader, returned as a `VgiFunction`
+ * (kind `"table"`) carrying the `copyFromFormat` metadata marker. Register it in
+ * the catalog's function list like any table function; the catalog's
+ * `copyFromFormats()` introspection picks it up and advertises the format.
+ */
+export declare function defineCopyFromFunction<TArgs = Record<string, unknown>>(config: CopyFromFunctionConfig<TArgs>): VgiFunction;