@query-farm/vgi 0.28.0 → 0.29.1

package/dist/catalog/interface.d.ts

@@ -95,14 +95,42 @@ export interface ScanFunctionResult {
     namedArguments: Record<string, unknown>;
     /** DuckDB extensions to load before calling the function. */
     requiredExtensions: string[];
+    /**
+     * Catalog schema path `functionName` is registered in (protocol 2.0.0). A function
+     * name is unique only within a schema, so a client that doesn't know this
+     * cannot tell which implementation a colliding name refers to — set it
+     * whenever the resolving code already knows the schema. `null` for a
+     * pre-1.5.0 peer, or when the resolved function is a native DuckDB function
+     * with no VGI-side schema of its own (e.g. `read_parquet`).
+     */
+    schemaPath: string[] | null;
 }
+/**
+ * Encode a ScanFunctionResult wire record — the single-row batch shape
+ * `{ function_name, arguments, required_extensions, schema_path }` that
+ * `catalog_table_scan_function_get` returns and that a function-backed table
+ * inlines into `TableInfo.scan_function`.
+ *
+ * It exists so there is exactly one place that names those columns. The
+ * inline-scan path used to restate the schema locally even though codegen
+ * emits it; a hand-written wire schema is how four SDKs ended up disagreeing
+ * about which columns were binary and which were large_binary.
+ *
+ * `argumentsBytes` is the already-serialized inner arguments batch (one column
+ * per argument: `arg_<index>` positional, bare name for named).
+ *
+ * `schemaPath` (protocol 2.0.0) identifies the schema that registers `functionName`;
+ * leave it null when the caller has no VGI-side schema to report.
+ */
+export declare function encodeScanFunctionResult(functionName: string, argumentsBytes: Uint8Array, requiredExtensions?: string[], schemaPath?: string[] | null): Uint8Array;
 /**
  * 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.
+ * `{ function_name: utf8, arguments: binary, required_extensions: list<utf8>,
+ * schema_path: 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;
 /**
@@ -119,6 +147,7 @@ export declare function singleBranchResult(legacy: {
     function_name: string;
     arguments: unknown;
     required_extensions?: string[];
+    schema_path?: string[] | null;
 }): {
     branches: Uint8Array[];
     required_extensions: string[];
@@ -149,16 +178,57 @@ export interface ScanBranchInput {
     branchFilter?: string | null;
     /** Declares this branch as the INSERT target (at most one per table). */
     writable?: boolean;
+    /** Custom file FORMAT this branch reads, for a format-backed branch. */
+    formatName?: string | null;
+    /** Locations the format branch reads. */
+    formatLocations?: string[] | null;
+    /** Reader options for a format branch, as a 1-row IPC batch whose COLUMN
+     *  NAMES are the option names — the same shape `arguments` uses, because an
+     *  option value may be any Arrow type. These BECOME the reader's named
+     *  arguments, so without them a format branch cannot pass its reader a
+     *  delimiter, a header flag, or anything else. */
+    formatOptions?: Uint8Array | null;
     /**
      * Catalog-table branch (lakehouse federation): leave `functionName` empty and
      * set these to scan the base table
-     * `sourceCatalog.sourceSchema.sourceTable` in a companion catalog instead of
+     * `sourceCatalog.sourceSchemaPath.sourceTable` in a companion catalog instead of
      * calling a table function.
      */
     sourceCatalog?: string | null;
-    sourceSchema?: string | null;
+    sourceSchemaPath?: string[] | null;
     sourceTable?: string | null;
+    /**
+     * Function branch only — the catalog schema that registers `functionName`
+     * (protocol 2.0.0). Without it a client has to guess (the table's own
+     * schema, then the catalog's default schema) which implementation
+     * `functionName` refers to when the same name is registered in more than
+     * one schema. Leave unset for a catalog-table or FORMAT branch, and for a
+     * branch that delegates straight to a native DuckDB function
+     * (`read_parquet`, `read_csv_auto`, `iceberg_scan`, …) — neither has a
+     * VGI-side schema of its own to report, which is why the field is optional
+     * rather than required. Not to be confused with `sourceSchemaPath` above, which
+     * names a catalog-table branch's *source table's* schema.
+     */
+    schemaPath?: string[] | null;
 }
+/**
+ * Serialize a single branch's arguments to the nested-IPC form `ScanBranch`
+ * expects: a 1-row batch with one column per argument — `arg_<index>` for
+ * positional args, the bare name for named args. Mirrors Python's
+ * `ScanBranch.to_row_dict` argument handling.
+ */
+/**
+ * Encode a format branch's reader options.
+ *
+ * Same shape as a branch's `arguments` blob — a 1-row batch whose COLUMN NAMES
+ * are the option names — because an option value may be any Arrow type, so no
+ * static schema could describe the map. Exported because a worker building a
+ * format branch needs it and has no other way to produce those bytes.
+ */
+export declare function encodeFormatOptions(options: Record<string, {
+    value: unknown;
+    type: VgiDataType;
+}>): Uint8Array;
 /**
  * Build a multi-branch `ScanBranchesResult` wire dict from explicit branch
  * definitions. Each branch becomes its own 1-row `ScanBranchSchema` IPC
@@ -213,23 +283,23 @@ export declare abstract class CatalogInterface {
     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>;
+    schemaGet(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Awaitable<SchemaInfo | null>;
+    schemaCreate(attachOpaqueData: AttachOpaqueData, path: string[], comment?: string | null, tags?: any, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    schemaDrop(attachOpaqueData: AttachOpaqueData, path: string[], ignoreNotFound?: boolean, cascade?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    schemaContentsTables(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Awaitable<TableInfo[]>;
+    schemaContentsViews(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Awaitable<ViewInfo[]>;
+    schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, path: string[], type: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<FunctionInfo[]>;
+    tableGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<TableInfo | null>;
+    tableCreate(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, columns: Uint8Array, onConflict: string, notNullConstraints?: number[], uniqueConstraints?: number[][], checkConstraints?: string[], transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableScanFunctionGet(attachOpaqueData: AttachOpaqueData, schemaPath: 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>;
+    tableScanBranchesGet(attachOpaqueData: AttachOpaqueData, schemaPath: 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
@@ -238,27 +308,27 @@ export declare abstract class CatalogInterface {
      * 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<{
+    tableColumnStatisticsGet(attachOpaqueData: AttachOpaqueData, schemaPath: 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, 
+    tableCommentSet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, comment?: string | null, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableRename(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, newName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnAdd(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, columnName: string, columnType: string, defaultValue?: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnRename(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, columnName: string, newName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnDefaultSet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, columnName: string, defaultValue: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnDefaultDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableColumnTypeChange(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, columnName: string, newType: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableNotNullSet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    tableNotNullDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    viewGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<ViewInfo | null>;
+    viewCreate(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, definition: string, onConflict: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    viewDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    viewRename(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, newName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    viewCommentSet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, comment?: string | null, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    macroGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<MacroInfo | null>;
+    macroCreate(attachOpaqueData: AttachOpaqueData, schemaPath: 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
@@ -266,10 +336,10 @@ export declare abstract class CatalogInterface {
      * 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>;
+    macroDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Awaitable<void>;
+    schemaContentsMacros(attachOpaqueData: AttachOpaqueData, path: string[], type: string, transactionOpaqueData?: TransactionOpaqueData): Awaitable<MacroInfo[]>;
+    schemaContentsIndexes(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Awaitable<IndexInfo[]>;
+    indexGet(attachOpaqueData: AttachOpaqueData, schemaPath: 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

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

@@ -1,5 +1,5 @@
 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 CatalogDescriptor } from "./descriptors.js";
 import type { FunctionRegistry } from "../functions/registry.js";
 import { type AttachOptionSpec } from "./attach-option.js";
 export declare class ReadOnlyCatalogInterface extends CatalogInterface {
@@ -8,6 +8,23 @@ export declare class ReadOnlyCatalogInterface extends CatalogInterface {
     private _attachments;
     private _version;
     constructor(descriptor: CatalogDescriptor, registry: FunctionRegistry);
+    /**
+     * Which schema declares `fn`, by object identity, or null if no schema does.
+     *
+     * A table's backing function is NOT necessarily declared in the table's own
+     * schema — `data.large_sequence` scans via `sequence`, which the example
+     * catalog declares in `main`. Populating `ScanFunctionResult.schemaPath` /
+     * `ScanBranch.schemaPath` (protocol 2.0.0) correctly needs this reverse
+     * lookup, not the `schemaPath` parameter of the call being served.
+     *
+     * Identity, not name: the whole point of the field is to disambiguate one
+     * name declared in several schemas, so a name match would answer the very
+     * question being asked. Null when the function is deliberately unadvertised
+     * (`cache_multicol`) — it has no schema to report and the client falls back
+     * to its own heuristic, which is exactly the pre-1.5.0 behaviour.
+     * Mirrors vgi-python's `ReadOnlyCatalogInterface._schema_for_function`.
+     */
+    private _schemaForFunction;
     catalogs(): string[];
     /**
      * Attach-time options this catalog declares, for the named catalog.
@@ -25,18 +42,18 @@ export declare class ReadOnlyCatalogInterface extends CatalogInterface {
     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): {
+    schemaGet(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): SchemaInfo | null;
+    schemaContentsTables(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo[]>;
+    tableColumnStatisticsGet(attachOpaqueData: AttachOpaqueData, schemaPath: 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[];
+    schemaContentsViews(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): ViewInfo[];
+    schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, path: string[], type: string, transactionOpaqueData?: TransactionOpaqueData): FunctionInfo[];
     /**
      * Build the wire `FunctionInfo` for one declared function.
      *
-     * `schemaName` is the schema the function actually lives in — it is the
+     * `schemaPath` is the schema the function actually lives in — it is the
      * bind-dispatch key, so a function advertised through more than one route
      * (schema contents *and* `global_functions`) must carry the same value in
      * both. Shared by `schemaContentsFunctions` and `_globalFunctionInfos`.
@@ -45,7 +62,7 @@ export declare class ReadOnlyCatalogInterface extends CatalogInterface {
     /**
      * Build `FunctionInfo` records for `CatalogDescriptor.globalFunctions`.
      *
-     * Each entry's `schema_name` is the schema it actually lives in — the
+     * Each entry's `schema_path` is the schema it actually lives in — the
      * globally visible name is derived client-side from
      * `global_function_prefix`, so `name` stays unprefixed here. An entry not
      * declared in any schema is a descriptor bug, so it throws rather than
@@ -53,12 +70,12 @@ export declare class ReadOnlyCatalogInterface extends CatalogInterface {
      * `_global_function_infos`.
      */
     private _globalFunctionInfos;
-    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;
+    schemaContentsMacros(attachOpaqueData: AttachOpaqueData, path: string[], type: string, transactionOpaqueData?: TransactionOpaqueData): MacroInfo[];
+    schemaContentsIndexes(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): IndexInfo[];
+    indexGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): IndexInfo | null;
+    macroGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): MacroInfo | null;
+    tableScanFunctionGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): any;
+    tableGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo | null>;
+    viewGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): ViewInfo | null;
     copyFromFormats(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): CopyFromFormatInfo[];
 }

package/dist/client/client.d.ts

@@ -10,7 +10,7 @@ import type { VgiClientOptions, TableFunctionOptions, ScalarFunctionOptions, Tab
  * Works with any RpcClient transport (subprocess or HTTP):
  * ```ts
  * import { subprocessConnect } from "@query-farm/vgi-rpc";
- * import { VgiClient, Arguments } from "vgi";
+ * import { VgiClient, Arguments } from "@query-farm/vgi";
  *
  * const rpc = subprocessConnect(["./my-worker"]);
  * const client = new VgiClient(rpc);
@@ -37,6 +37,13 @@ export declare class VgiClient {
      * attached catalogs.
      */
     constructor(rpc: RpcClient, options?: VgiClientOptions);
+    /**
+     * Connect the high-level client to a canonical `iroh://` or `httpi://`
+     * endpoint. Native Node/Bun connectors are selected from the URI scheme.
+     * Browser callers may inject the connector exported by the browser Iroh
+     * package without changing the VGI client API.
+     */
+    static fromIroh(endpoint: string, options?: Record<string, unknown>, clientOptions?: VgiClientOptions, connector?: (endpoint: string, options: Record<string, unknown>) => Promise<RpcClient>): Promise<VgiClient>;
     private _doBind;
     private _doInit;
     /** Call a table function, yielding output as RecordBatch instances. */
@@ -112,48 +119,48 @@ export declare class VgiClient {
     /** 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>;
+    schemaGet(attachOpaqueData: AttachOpaqueData, path: string[] | string, transactionOpaqueData?: TransactionOpaqueData): Promise<SchemaInfo | null>;
     /** Create a new schema. */
-    schemaCreate(attachOpaqueData: AttachOpaqueData, name: string, opts?: {
+    schemaCreate(attachOpaqueData: AttachOpaqueData, path: string[] | 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>;
+    schemaDrop(attachOpaqueData: AttachOpaqueData, path: string[] | string, ignoreNotFound?: boolean, cascade?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
     /** List tables in a schema. */
-    schemaContentsTables(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo[]>;
+    schemaContentsTables(attachOpaqueData: AttachOpaqueData, path: string[] | string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo[]>;
     /** List views in a schema. */
-    schemaContentsViews(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo[]>;
+    schemaContentsViews(attachOpaqueData: AttachOpaqueData, path: string[] | string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo[]>;
     /** List functions in a schema, filtered by type. */
-    schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, name: string, type: CatalogFunctionType, transactionOpaqueData?: TransactionOpaqueData): Promise<FunctionInfo[]>;
+    schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, path: string[] | 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>;
+    tableGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableCreate(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableScanFunctionGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableCommentSet(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableRename(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableColumnAdd(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableColumnDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableColumnRename(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableColumnDefaultSet(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableColumnDefaultDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | string, name: string, columnName: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
     /**
      * Change the type of a column.
      *
@@ -161,29 +168,29 @@ export declare class VgiClient {
      * 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>;
+    tableColumnTypeChange(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableNotNullSet(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    tableNotNullDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    viewGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    viewCreate(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    viewDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    viewRename(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    viewCommentSet(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    macroGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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[]>;
+    schemaContentsMacros(attachOpaqueData: AttachOpaqueData, path: string[] | 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>;
+    macroCreate(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | 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>;
+    macroDrop(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | string, name: string, ignoreNotFound?: boolean, transactionOpaqueData?: TransactionOpaqueData): Promise<void>;
     /** Close the underlying RPC connection. */
     close(): void;
 }

package/dist/client/types.d.ts

@@ -40,6 +40,8 @@ export interface CatalogAttachOptions {
     optionsBytes?: Uint8Array;
     dataVersionSpec?: string | null;
     implementationVersion?: string | null;
+    /** Engine capabilities serialized into the protocol's named inner record. */
+    clientCapabilities?: import("../generated/vgi-client.js").ClientCapabilities | null;
 }
 /** Conflict resolution strategy for create operations. */
 export type OnCreateConflict = "error" | "ignore" | "replace";

package/dist/client-entry.d.ts

@@ -2,7 +2,7 @@ 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 { FunctionType, FunctionStability, NullHandling, ArgumentMonotonicity, 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";