@query-farm/vgi 0.6.0

package/dist/catalog/interface.d.ts

@@ -0,0 +1,239 @@
+export type AttachOpaqueData = Uint8Array;
+export type TransactionOpaqueData = Uint8Array;
+import type { MacroType } from "../generated/vgi-client.js";
+export type { MacroType };
+import type { CatalogAttachResult } from "../generated/vgi-client.js";
+export type { CatalogAttachResult };
+import type { SchemaInfo } from "../generated/vgi-client.js";
+export type { SchemaInfo };
+export { encodeSchemaInfo, decodeSchemaInfo } from "../generated/vgi-client.js";
+import type { CatalogInfo } from "../generated/vgi-client.js";
+export type { CatalogInfo };
+export { encodeCatalogInfo, decodeCatalogInfo } from "../generated/vgi-client.js";
+import type { TableInfo } from "../generated/vgi-client.js";
+export type { TableInfo };
+export { encodeTableInfo, decodeTableInfo } from "../generated/vgi-client.js";
+import type { ViewInfo } from "../generated/vgi-client.js";
+export type { ViewInfo };
+export { encodeViewInfo, decodeViewInfo } from "../generated/vgi-client.js";
+import type { FunctionInfo } from "../generated/vgi-client.js";
+export type { FunctionInfo };
+/** @deprecated Use the FunctionInfo interface (snake_case) directly. */
+export type FunctionInfoOptions = FunctionInfo;
+export { encodeFunctionInfo, decodeFunctionInfo } from "../generated/vgi-client.js";
+import type { MacroInfo } from "../generated/vgi-client.js";
+export type { MacroInfo };
+export { encodeMacroInfo, decodeMacroInfo } from "../generated/vgi-client.js";
+import type { IndexInfo, IndexConstraintType } from "../generated/vgi-client.js";
+export type { IndexInfo, IndexConstraintType };
+export { encodeIndexInfo, decodeIndexInfo } from "../generated/vgi-client.js";
+export interface CopyFromFormatInfo {
+    /** Free-text comment (CopyFromFunction's `copyFromComment`). */
+    comment?: string | null;
+    /** Function/format tags. */
+    tags: Record<string, string>;
+    /** The `FORMAT` identifier users type (single global namespace). */
+    format_name: string;
+    /** Registered name of the worker function that performs the read. */
+    handler: string;
+    /**
+     * Serialized Arrow schema of the format's options (same encoding as
+     * `FunctionInfo.arguments`), each field carrying type / `vgi_doc` description.
+     */
+    options: Uint8Array;
+    /** `"from"` / `"to"` / `"both"` — the COPY direction this format serves. */
+    direction: string;
+    /** Intrinsic documentation from the handler's description. */
+    description: string;
+    /**
+     * COPY ... TO only — when true the writer requires rows in source order, so
+     * the extension uses a single-threaded sink (`REGULAR_COPY_TO_FILE`) instead
+     * of the default parallel sharded write. Set via `Meta.sinkOrderDependent`
+     * on a CopyToFunction; always false for readers. Mirrors vgi-python's
+     * `CopyFromFormatInfo.ordered`.
+     */
+    ordered: boolean;
+}
+/** Encode a CopyFromFormatInfo to Arrow IPC bytes (single-row batch). */
+export declare const encodeCopyFromFormatInfo: (v: CopyFromFormatInfo) => Uint8Array;
+import { type VgiDataType } from "../arrow/index.js";
+/**
+ * Result from `tableScanFunctionGet` — tells the VGI DuckDB extension which
+ * DuckDB function to call to obtain the data for a table.
+ */
+export interface ScanFunctionResult {
+    /** The DuckDB function to call (e.g. "read_parquet"). */
+    functionName: string;
+    /** Positional arguments, decoded from the inner Arrow batch. */
+    positionalArguments: unknown[];
+    /** Named arguments, decoded from the inner Arrow batch. */
+    namedArguments: Record<string, unknown>;
+    /** DuckDB extensions to load before calling the function. */
+    requiredExtensions: string[];
+}
+/**
+ * Decode a ScanFunctionResult from a wire-shape inner result dict.
+ *
+ * The wire shape (per ScanFunctionResultSchema) is
+ * `{ function_name: utf8, arguments: binary, required_extensions: list<utf8> }`,
+ * where `arguments` is a serialized single-row batch with one column per
+ * argument: `arg_<index>` for positional args, the bare name for named args.
+ */
+export declare function decodeScanFunctionResult(inner: Record<string, unknown>): ScanFunctionResult;
+/**
+ * Synthesise a one-branch `ScanBranchesResult` wire dict from a legacy
+ * `tableScanFunctionGet` wire result. Mirrors vgi-python's default
+ * `table_scan_branches_get` (catalog_interface.py): a single-source worker is
+ * automatically compatible with the branches-aware C++ side.
+ *
+ * Each branch is its own IPC stream carried in a `list<binary>` column. The
+ * legacy result's `arguments` field is already the nested-IPC form
+ * `ScanBranch` expects, so it passes through untouched.
+ */
+export declare function singleBranchResult(legacy: {
+    function_name: string;
+    arguments: unknown;
+    required_extensions?: string[];
+}): {
+    branches: Uint8Array[];
+    required_extensions: string[];
+};
+/**
+ * One physical source backing a multi-branch scan, in the shape the
+ * `buildScanBranchesResult` helper consumes. Mirrors vgi-python's
+ * `ScanBranch` (catalog_interface.py).
+ *
+ * Each scalar argument carries an explicit Arrow `type` so the nested
+ * arguments batch is built with the wire type the C++ binder expects
+ * (e.g. utf8 for file paths, int64 for counts).
+ */
+export interface ScanBranchInput {
+    /** DuckDB function to call for this branch (e.g. "sequence", "read_parquet"). */
+    functionName: string;
+    /** Positional scalar arguments, each with its Arrow type. */
+    positionalArguments?: {
+        value: unknown;
+        type: VgiDataType;
+    }[];
+    /** Named scalar arguments, each with its Arrow type. */
+    namedArguments?: Record<string, {
+        value: unknown;
+        type: VgiDataType;
+    }>;
+    /** Optional SQL filter text AND'd into every scan of this branch. */
+    branchFilter?: string | null;
+    /** Declares this branch as the INSERT target (at most one per table). */
+    writable?: boolean;
+}
+/**
+ * Build a multi-branch `ScanBranchesResult` wire dict from explicit branch
+ * definitions. Each branch becomes its own 1-row `ScanBranchSchema` IPC
+ * stream carried in the `branches` list<binary> column. Mirrors vgi-python's
+ * `ScanBranchesResult` construction in the test fixture's
+ * `table_scan_branches_get`.
+ *
+ * An empty `branches` list is serialized verbatim — the C++ side loud-fails
+ * on it (that asymmetry is exercised by multi_branch_empty_branches.test).
+ */
+export declare function buildScanBranchesResult(branches: ScanBranchInput[], requiredExtensions?: string[]): {
+    branches: Uint8Array[];
+    required_extensions: string[];
+};
+/**
+ * Catalog method return type — sync `T` or `Promise<T>`. The framework's
+ * dispatch handlers `await` every catalog call, so async overrides work
+ * out of the box. Default impls return sync values.
+ */
+type Awaitable<T> = T | Promise<T>;
+export declare abstract class CatalogInterface {
+    abstract catalogs(): string[];
+    /**
+     * Attach this catalog. The framework already validates ATTACH options
+     * (name + type) against the specs the worker advertises in
+     * `catalogsInfo().attach_option_specs`, so `options` arrives as a
+     * validated, decoded `{name: value}` dict with typed column values.
+     * Use `{}` if no options were supplied.
+     */
+    abstract attach(name: string, options?: Record<string, unknown>, dataVersionSpec?: string | null, implementationVersion?: string | null): Awaitable<CatalogAttachResult>;
+    /**
+     * List the catalogs this worker exposes with their version metadata. The
+     * `implementation_version` / `data_version_spec` come from the CatalogInfo
+     * returned by the read-only catalogs() signature below — a versioned worker
+     * overrides `catalogs()` / `catalogsInfo()` to advertise real values; the
+     * default derives them from the registered descriptor(s).
+     */
+    catalogsInfo?(): Awaitable<import("../generated/vgi-client.js").CatalogInfo[]>;
+    abstract detach(attachOpaqueData: AttachOpaqueData): Awaitable<void>;
+    abstract version(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Awaitable<number>;
+    abstract schemas(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Awaitable<SchemaInfo[]>;
+    create(name: string, onConflict: string, options?: any): Awaitable<void>;
+    drop(name: string): Awaitable<void>;
+    schemaGet(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<SchemaInfo | null>;
+    schemaCreate(attachOpaqueData: AttachOpaqueData, name: string, comment?: string | null, tags?: any, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    schemaDrop(attachOpaqueData: AttachOpaqueData, name: string, ignoreNotFound?: boolean, cascade?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    schemaContentsTables(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<TableInfo[]>;
+    schemaContentsViews(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<ViewInfo[]>;
+    schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, name: string, type: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<FunctionInfo[]>;
+    tableGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<TableInfo | null>;
+    tableCreate(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columns: Uint8Array, onConflict: string, notNullConstraints?: number[], uniqueConstraints?: number[][], checkConstraints?: string[], transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableScanFunctionGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<any>;
+    /**
+     * Return the scan branches for a (possibly multi-source) table. Default
+     * delegates to `tableScanFunctionGet` and wraps the single result as a
+     * one-branch list, so every single-source catalog is compatible with the
+     * branches-aware C++ extension. Override for genuine multi-source tables.
+     */
+    tableScanBranchesGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<any>;
+    /**
+     * Return serialized column statistics for a table, or null if none are
+     * available. The result is the IPC bytes of a ColumnStatistics RecordBatch
+     * (see src/util/statistics.ts for the schema) wrapped with an optional
+     * cache TTL. Callers typically override this to pull stats from a
+     * descriptor. Returning null signals "no stats" so DuckDB falls back to
+     * the function-level `table_function_statistics` path.
+     */
+    tableColumnStatisticsGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<{
+        bytes: Uint8Array;
+        cacheMaxAgeSeconds: number | null;
+    } | null>;
+    tableCommentSet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, comment?: string | null, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableRename(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, newName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnAdd(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, columnType: string, defaultValue?: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnRename(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, newName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnDefaultSet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, defaultValue: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnDefaultDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnTypeChange(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, newType: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableNotNullSet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableNotNullDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    viewGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<ViewInfo | null>;
+    viewCreate(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, definition: string, onConflict: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    viewDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    viewRename(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, newName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    viewCommentSet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, comment?: string | null, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    macroGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<MacroInfo | null>;
+    macroCreate(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, macroType: MacroType, parameters: string[], definition: string, onConflict: string, parameterDefaultValues?: Uint8Array | null, 
+    /**
+     * Optional Arrow schema (one nullable field per parameter, in `parameters`
+     * order) serialized as IPC bytes, carrying per-parameter descriptions via the
+     * `vgi_doc` field metadata key. `null`/omitted when no per-parameter docs are
+     * supplied. Build with `macroArgumentsSchema` + `serializeSchema`.
+     */
+    argumentsSchema?: Uint8Array | null, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    macroDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    schemaContentsMacros(attachOpaqueData: AttachOpaqueData, name: string, type: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<MacroInfo[]>;
+    schemaContentsIndexes(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<IndexInfo[]>;
+    indexGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<IndexInfo | null>;
+    /**
+     * List custom `COPY ... FROM` formats advertised by this catalog. Catalog-level
+     * (not schema-scoped). The default returns an empty list, so catalogs that
+     * don't define COPY formats are unaffected. The VGI extension treats an empty
+     * list (or a not-implemented method) as "no custom formats". Mirrors
+     * vgi-python's `CatalogInterface.copy_from_formats`.
+     */
+    copyFromFormats(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Awaitable<CopyFromFormatInfo[]>;
+    transactionBegin(attachOpaqueData: AttachOpaqueData): Awaitable<Uint8Array | null>;
+    transactionCommit(attachOpaqueData: AttachOpaqueData, transactionOpaqueData: TransactionOpaqueData): Awaitable<void>;
+    transactionRollback(attachOpaqueData: AttachOpaqueData, transactionOpaqueData: TransactionOpaqueData): Awaitable<void>;
+}

package/dist/catalog/read-only.d.ts

@@ -0,0 +1,33 @@
+import { CatalogInterface, type AttachOpaqueData, type TransactionOpaqueData, type CatalogAttachResult, type SchemaInfo, type CatalogInfo, type TableInfo, type ViewInfo, type FunctionInfo, type MacroInfo, type IndexInfo, type CopyFromFormatInfo } from "./interface.js";
+import type { CatalogDescriptor } from "./descriptors.js";
+import type { FunctionRegistry } from "../functions/registry.js";
+export declare class ReadOnlyCatalogInterface extends CatalogInterface {
+    private _descriptor;
+    private _registry;
+    private _attachments;
+    private _version;
+    constructor(descriptor: CatalogDescriptor, registry: FunctionRegistry);
+    catalogs(): string[];
+    catalogsInfo(): CatalogInfo[];
+    attach(name: string, options?: Record<string, unknown>, dataVersionSpec?: string | null, implementationVersion?: string | null): CatalogAttachResult | Promise<CatalogAttachResult>;
+    detach(attachOpaqueData: AttachOpaqueData): void;
+    version(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): number | Promise<number>;
+    schemas(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): SchemaInfo[];
+    private _estimatedObjectCount;
+    schemaGet(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): SchemaInfo | null;
+    schemaContentsTables(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo[]>;
+    tableColumnStatisticsGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): {
+        bytes: Uint8Array;
+        cacheMaxAgeSeconds: number | null;
+    } | null;
+    schemaContentsViews(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): ViewInfo[];
+    schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, name: string, type: string, transactionOpaqueData?: TransactionOpaqueData): FunctionInfo[];
+    schemaContentsMacros(attachOpaqueData: AttachOpaqueData, name: string, type: string, transactionOpaqueData?: TransactionOpaqueData): MacroInfo[];
+    schemaContentsIndexes(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): IndexInfo[];
+    indexGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): IndexInfo | null;
+    macroGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): MacroInfo | null;
+    tableScanFunctionGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): any;
+    tableGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo | null>;
+    viewGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): ViewInfo | null;
+    copyFromFormats(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): CopyFromFormatInfo[];
+}

package/dist/client/client.d.ts

@@ -0,0 +1,189 @@
+import { type VgiBatch } from "../arrow/index.js";
+import { type RpcClient } from "@query-farm/vgi-rpc";
+import { type SchemaInfo, type TableInfo, type ViewInfo, type FunctionInfo, type MacroInfo, type MacroType, type CatalogAttachResult, type AttachOpaqueData, type TransactionOpaqueData, type CatalogInfo, type ScanFunctionResult } from "../catalog/interface.js";
+import { VgiClientError } from "./errors.js";
+export { VgiClientError };
+import type { VgiClientOptions, TableFunctionOptions, ScalarFunctionOptions, TableInOutFunctionOptions, OnCreateConflict, CatalogFunctionType, CatalogMacroType, CatalogAttachOptions, AttachOptionValue } from "./types.js";
+/**
+ * High-level client for calling VGI worker functions and catalog API.
+ *
+ * Works with any RpcClient transport (subprocess or HTTP):
+ * ```ts
+ * import { subprocessConnect } from "@query-farm/vgi-rpc";
+ * import { VgiClient, Arguments } from "vgi";
+ *
+ * const rpc = subprocessConnect(["./my-worker"]);
+ * const client = new VgiClient(rpc);
+ *
+ * for await (const rows of client.tableFunctionRows({
+ *   functionName: "sequence",
+ *   arguments: new Arguments([10]),
+ * })) {
+ *   console.log(rows);
+ * }
+ * client.close();
+ * ```
+ */
+export declare class VgiClient {
+    private readonly rpc;
+    private readonly defaultAttachOpaqueData;
+    /**
+     * Construct a VgiClient wrapping an `RpcClient` transport.
+     *
+     * `options.attachOpaqueData` sets a client-wide default attach ID used by every
+     * function call that doesn't supply its own. Per-call `attachOpaqueData` on
+     * `TableFunctionOptions`/`ScalarFunctionOptions`/`TableInOutFunctionOptions`
+     * takes precedence — useful when a single client talks to multiple
+     * attached catalogs.
+     */
+    constructor(rpc: RpcClient, options?: VgiClientOptions);
+    private _doBind;
+    private _doInit;
+    /** Call a table function, yielding output as RecordBatch instances. */
+    tableFunction(opts: TableFunctionOptions): AsyncGenerator<VgiBatch>;
+    /** Call a scalar function, yielding output as row objects. */
+    scalarFunctionRows(opts: ScalarFunctionOptions): AsyncGenerator<Record<string, any>[]>;
+    /** Call a scalar function, yielding output as RecordBatch instances. */
+    scalarFunction(opts: ScalarFunctionOptions): AsyncGenerator<VgiBatch>;
+    /** Call a table-in-out function, yielding output as row objects. */
+    tableInOutFunctionRows(opts: TableInOutFunctionOptions): AsyncGenerator<Record<string, any>[]>;
+    /** Call a table-in-out function, yielding output as RecordBatch instances. */
+    tableInOutFunction(opts: TableInOutFunctionOptions): AsyncGenerator<VgiBatch>;
+    /** Call a table function, yielding output as row objects. */
+    tableFunctionRows(opts: TableFunctionOptions): AsyncGenerator<Record<string, any>[]>;
+    /**
+     * List all catalogs with their advertised version metadata.
+     *
+     * Each entry has `{name, implementation_version?, data_version_spec?}`.
+     * Versioned workers populate the version fields; read-only workers
+     * leave both null.
+     */
+    catalogsInfo(): Promise<CatalogInfo[]>;
+    /** List all available catalog names (shorthand for `catalogsInfo().map(c => c.name)`). */
+    catalogs(): Promise<string[]>;
+    /**
+     * Attach a catalog by name. Returns connection details including the
+     * attachOpaqueData.
+     *
+     * `opts.options` is a plain key→value map; column types are inferred from
+     * the value at runtime (see AttachOptionValue for the mapping). Use
+     * `opts.optionsBytes` instead when you need Arrow types the inference
+     * can't express (Decimal, Timestamp, Int32 vs Int64, nested structs).
+     * Providing both throws.
+     *
+     * Versioned catalogs (see vgi-example-versioned-worker) validate
+     * `dataVersionSpec` / `implementationVersion` at attach time and echo
+     * back the resolved values on the result — callers can read those from
+     * `result.resolved_data_version` / `result.resolved_implementation_version`.
+     *
+     * @example
+     * ```ts
+     * const result = await client.catalogAttach("my_catalog", {
+     *   options: { region: "us-east-1", maxCachedRows: 1000n, readOnly: true },
+     *   dataVersionSpec: "1.0.0",
+     * });
+     * ```
+     */
+    catalogAttach(name: string, opts?: CatalogAttachOptions): Promise<CatalogAttachResult>;
+    /** Detach a previously-attached catalog. */
+    catalogDetach(attachOpaqueData: AttachOpaqueData): Promise<void>;
+    /**
+     * Create a new catalog.
+     *
+     * `options` is a plain key→value map; column types are inferred from the
+     * value at runtime (see AttachOptionValue). Use `optionsBytes` instead
+     * when you need Arrow types the inference can't express. Providing both
+     * throws.
+     */
+    catalogCreate(name: string, onConflict: OnCreateConflict, options?: Uint8Array | {
+        options?: Record<string, AttachOptionValue>;
+        optionsBytes?: Uint8Array;
+    }): Promise<void>;
+    /** Drop a catalog by name. */
+    catalogDrop(name: string): Promise<void>;
+    /** Get the current catalog version number. */
+    catalogVersion(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Promise<number>;
+    /** Begin a new transaction. Returns the transaction ID. */
+    transactionBegin(attachOpaqueData: AttachOpaqueData): Promise<Uint8Array>;
+    /** Commit a transaction. */
+    transactionCommit(attachOpaqueData: AttachOpaqueData, transactionOpaqueData: TransactionOpaqueData): Promise<void>;
+    /** Rollback a transaction. */
+    transactionRollback(attachOpaqueData: AttachOpaqueData, transactionOpaqueData: TransactionOpaqueData): Promise<void>;
+    /** List schemas in an attached catalog. */
+    schemas(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Promise<SchemaInfo[]>;
+    /** Get a schema by name, or null if not found. */
+    schemaGet(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<SchemaInfo | null>;
+    /** Create a new schema. */
+    schemaCreate(attachOpaqueData: AttachOpaqueData, name: string, opts?: {
+        onConflict?: OnCreateConflict;
+        comment?: string | null;
+        tags?: Record<string, string> | null;
+        transactionOpaqueData?: TransactionOpaqueData;
+    }): Promise<void>;
+    /** Drop a schema by name. */
+    schemaDrop(attachOpaqueData: AttachOpaqueData, name: string, ignoreNotFound?: boolean, cascade?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** List tables in a schema. */
+    schemaContentsTables(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo[]>;
+    /** List views in a schema. */
+    schemaContentsViews(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo[]>;
+    /** List functions in a schema, filtered by type. */
+    schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, name: string, type: CatalogFunctionType, transactionOpaqueData?: TransactionOpaqueData): Promise<FunctionInfo[]>;
+    /** Get a table by name, or null if not found. */
+    tableGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo | null>;
+    /** Create a new table. */
+    tableCreate(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columns: Uint8Array, onConflict: OnCreateConflict, notNullConstraints?: number[], uniqueConstraints?: number[][], checkConstraints?: string[], transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Drop a table by name. */
+    tableDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, ignoreNotFound?: boolean, cascade?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /**
+     * Get the scan function for a table — tells DuckDB which function to call
+     * to read the table data (e.g. `read_parquet` with a path argument). Used
+     * by the VGI extension during query planning.
+     */
+    tableScanFunctionGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string | null, atValue?: string | null, transactionOpaqueData?: TransactionOpaqueData): Promise<ScanFunctionResult>;
+    /** Set or clear the comment on a table. */
+    tableCommentSet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, comment?: string | null, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Rename a table. */
+    tableRename(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, newName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Add a column to a table. */
+    tableColumnAdd(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, columnType: string, defaultValue?: string | null, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Drop a column from a table. */
+    tableColumnDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Rename a column in a table. */
+    tableColumnRename(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, newName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Set the default value for a column. */
+    tableColumnDefaultSet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, defaultValue: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Remove the default value from a column. */
+    tableColumnDefaultDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /**
+     * Change the type of a column.
+     *
+     * `columnDefinition` is a serialized Arrow Schema with a single field whose
+     * name identifies the target column and whose type is the new column type.
+     * `expression` is an optional SQL expression used to convert existing values.
+     */
+    tableColumnTypeChange(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnDefinition: Uint8Array, expression?: string | null, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Set a NOT NULL constraint on a column. */
+    tableNotNullSet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Remove a NOT NULL constraint from a column. */
+    tableNotNullDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Get a view by name, or null if not found. */
+    viewGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo | null>;
+    /** Create a new view. */
+    viewCreate(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, definition: string, onConflict: OnCreateConflict, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Drop a view by name. */
+    viewDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, ignoreNotFound?: boolean, cascade?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Rename a view. */
+    viewRename(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, newName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Set or clear the comment on a view. */
+    viewCommentSet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, comment?: string | null, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Get a macro by name, or null if not found. */
+    macroGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo | null>;
+    /** List macros in a schema, filtered by type. */
+    schemaContentsMacros(attachOpaqueData: AttachOpaqueData, name: string, type: CatalogMacroType, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo[]>;
+    /** Create a new macro. */
+    macroCreate(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, macroType: MacroType, parameters: string[], definition: string, onConflict: OnCreateConflict, parameterDefaultValues?: Uint8Array | null, argumentsSchema?: Uint8Array | null, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Drop a macro by name. */
+    macroDrop(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
+    /** Close the underlying RPC connection. */
+    close(): void;
+}

package/dist/client/errors.d.ts

@@ -0,0 +1,26 @@
+import { RpcError, type RpcClient } from "@query-farm/vgi-rpc";
+/** Error thrown by VgiClient when an RPC call fails or returns unexpected data. */
+export declare class VgiClientError extends Error {
+    /** Remote traceback from the worker, when an RpcError carried one. */
+    readonly remoteTraceback?: string;
+    /** Underlying error type from the worker (e.g. "ValueError"), when known. */
+    readonly errorType?: string;
+    constructor(message: string, options?: {
+        remoteTraceback?: string;
+        errorType?: string;
+        cause?: unknown;
+    });
+    /**
+     * Build a VgiClientError from an underlying RpcError, preserving the
+     * remote error type, message, and traceback so the worker-raised exception
+     * shows up at the top of the stack rather than buried under VGI framing.
+     * Mirrors Python's ClientError.from_rpc_error.
+     */
+    static fromRpcError(e: RpcError): VgiClientError;
+}
+/**
+ * Wrap an RpcClient so any RpcError thrown by call/stream is rethrown as a
+ * VgiClientError carrying the worker's remote traceback. Other errors
+ * propagate unchanged.
+ */
+export declare function wrapRpcWithErrorEnrichment(rpc: RpcClient): RpcClient;

package/dist/client/helpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Deserialize a List<Binary> of serialized info batches into typed info objects.
+ */
+export declare function deserializeInfoList<T>(items: unknown, deserializeFn: (bytes: Uint8Array) => T): T[];
+/**
+ * Deserialize Arrow Map entries into a plain Record<string, string>.
+ */
+export declare function deserializeTags(mapVal: unknown): Record<string, string>;
+/**
+ * Convert sync/async iterable to async iterator.
+ */
+export declare function toAsyncIterator<T>(input: Iterable<T> | AsyncIterable<T>): AsyncIterator<T>;

package/dist/client/protocol.d.ts

@@ -0,0 +1,16 @@
+import { toUint8Array } from "../util/bytes.js";
+import type { VgiBatch } from "../arrow/index.js";
+export { toUint8Array };
+/**
+ * Wrap a RecordBatch as a { request: Uint8Array } dict for RPC params.
+ * DuckDB wraps ArrowSerializableDataclass params in a single "request" Binary column.
+ */
+export declare function wrapRequest(batch: VgiBatch): {
+    request: Uint8Array;
+};
+/**
+ * Unwrap a { result: Uint8Array } response dict.
+ * The "result" Binary column contains a serialized inner batch;
+ * returns its row 0 as a flat dict.
+ */
+export declare function unwrapResult(result: Record<string, any>): Record<string, any>;

package/dist/client/types.d.ts

@@ -0,0 +1,125 @@
+import type { VgiBatch } from "../arrow/index.js";
+import type { Arguments } from "../arguments/arguments.js";
+import type { AttachOptionValue } from "../catalog/attach-options.js";
+import type { BindResponse } from "../protocol/types.js";
+import { OrderByDirection, OrderByNullOrder } from "../protocol/types.js";
+export type { AttachOptionValue };
+export { OrderByDirection, OrderByNullOrder };
+/** ORDER BY pushdown hint passed at init time. */
+export interface OrderByPushdown {
+    columnName: string;
+    direction: OrderByDirection;
+    nullOrder: OrderByNullOrder;
+    /** Optional LIMIT to combine with ORDER BY. */
+    limit?: bigint | number | null;
+}
+/** TABLESAMPLE pushdown hint passed at init time. */
+export interface TablesamplePushdown {
+    /** Sample percentage in [0, 100]. */
+    percentage: number;
+    /** Optional sampling seed. */
+    seed?: bigint | number | null;
+}
+/** Callback invoked after a successful bind, before init. */
+export type BindResultCallback = (response: BindResponse) => void;
+/**
+ * Options bag for VgiClient.catalogAttach.
+ *
+ * Pass `options` as a plain key→value map — the client serializes to an
+ * Arrow RecordBatch with per-value type inference (see AttachOptionValue).
+ * For Arrow types that inference can't express (Decimal, Timestamp, exact
+ * int width, nested struct), use `optionsBytes` to supply pre-serialized
+ * bytes. Providing both throws.
+ *
+ * `dataVersionSpec` / `implementationVersion` are sent to versioned
+ * catalogs for attach-time validation; workers that aren't versioned
+ * ignore them.
+ */
+export interface CatalogAttachOptions {
+    options?: Record<string, AttachOptionValue>;
+    optionsBytes?: Uint8Array;
+    dataVersionSpec?: string | null;
+    implementationVersion?: string | null;
+}
+/** Conflict resolution strategy for create operations. */
+export type OnCreateConflict = "error" | "ignore" | "replace";
+/** DuckDB catalog function type filter (sent as uppercase wire values). */
+export type CatalogFunctionType = "SCALAR_FUNCTION" | "TABLE_FUNCTION";
+/** Macro type filter for schema contents listing (uppercase wire values). */
+export type CatalogMacroType = "SCALAR_MACRO" | "TABLE_MACRO";
+/** Options for constructing a VgiClient. */
+export interface VgiClientOptions {
+    /** Pre-existing attach ID to bind this client to a specific catalog. */
+    attachOpaqueData?: Uint8Array;
+}
+/** Options for calling a table function. */
+export interface TableFunctionOptions {
+    /** Name of the function to call. */
+    functionName: string;
+    /** Positional and named arguments. */
+    arguments?: Arguments;
+    /** Column indices to project (filter pushdown). */
+    projectionIds?: number[];
+    /** Filter pushdown batch. */
+    pushdownFilters?: VgiBatch;
+    /** DuckDB settings to pass to the function. */
+    settings?: VgiBatch;
+    /** Transaction ID for transactional catalogs. */
+    transactionOpaqueData?: Uint8Array;
+    /** Attach ID to bind this call to a specific catalog attach. Overrides the client-level attachOpaqueData. */
+    attachOpaqueData?: Uint8Array;
+    /** ORDER BY pushdown hint from DuckDB's RowGroupPruner. */
+    orderBy?: OrderByPushdown;
+    /** TABLESAMPLE pushdown hint from DuckDB's SamplingPushdown optimizer. */
+    tablesample?: TablesamplePushdown;
+    /** Join-key value batches, one per join-keys column. */
+    joinKeys?: VgiBatch[];
+    /** Invoked after bind, before init. Receives the bind response. */
+    onBind?: BindResultCallback;
+}
+/** Options for calling a scalar function. */
+export interface ScalarFunctionOptions {
+    /** Name of the function to call. */
+    functionName: string;
+    /** Input batches to process. */
+    input: Iterable<VgiBatch> | AsyncIterable<VgiBatch>;
+    /** Positional and named arguments. */
+    arguments?: Arguments;
+    /** DuckDB settings to pass to the function. */
+    settings?: VgiBatch;
+    /** DuckDB secrets to pass to the function. */
+    secrets?: VgiBatch;
+    /** Transaction ID for transactional catalogs. */
+    transactionOpaqueData?: Uint8Array;
+    /** Attach ID to bind this call to a specific catalog attach. Overrides the client-level attachOpaqueData. */
+    attachOpaqueData?: Uint8Array;
+    /** Invoked after bind, before init. Receives the bind response. */
+    onBind?: BindResultCallback;
+}
+/** Options for calling a table-in-out function. */
+export interface TableInOutFunctionOptions {
+    /** Name of the function to call. */
+    functionName: string;
+    /** Input batches to process. */
+    input: Iterable<VgiBatch> | AsyncIterable<VgiBatch>;
+    /** Positional and named arguments. */
+    arguments?: Arguments;
+    /** Column indices to project (filter pushdown). */
+    projectionIds?: number[];
+    /** Filter pushdown batch. */
+    pushdownFilters?: VgiBatch;
+    /** DuckDB settings to pass to the function. */
+    settings?: VgiBatch;
+    /** Transaction ID for transactional catalogs. */
+    transactionOpaqueData?: Uint8Array;
+    /** Attach ID to bind this call to a specific catalog attach. Overrides the client-level attachOpaqueData. */
+    attachOpaqueData?: Uint8Array;
+    /** ORDER BY pushdown hint from DuckDB's RowGroupPruner. */
+    orderBy?: OrderByPushdown;
+    /** TABLESAMPLE pushdown hint from DuckDB's SamplingPushdown optimizer. */
+    tablesample?: TablesamplePushdown;
+    /** Join-key value batches, one per join-keys column. */
+    joinKeys?: VgiBatch[];
+    /** Invoked after bind, before init. Receives the bind response. */
+    onBind?: BindResultCallback;
+}