@query-farm/vgi 0.29.0 → 0.29.1

package/README.md

@@ -1,4 +1,20 @@
-# @query-farm/vgi
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Query-farm/vgi-typescript/main/docs/vgi-logo.png" alt="Vector Gateway Interface logo" width="320">
+</p>
+
+<h1 align="center">VGI for TypeScript</h1>
+
+<p align="center">
+  Add your own functions and tables to DuckDB with TypeScript and Apache Arrow.<br>
+  Built by <a href="https://query.farm">🚜 Query.Farm</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Query-farm/vgi-typescript/actions/workflows/ci.yml"><img src="https://github.com/Query-farm/vgi-typescript/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@query-farm/vgi"><img src="https://img.shields.io/npm/v/%40query-farm%2Fvgi" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/@query-farm/vgi"><img src="https://img.shields.io/npm/dm/%40query-farm%2Fvgi" alt="npm downloads"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Query%20Farm%20Source--Available-blue" alt="License"></a>
+</p>
 
 TypeScript framework for extending [DuckDB](https://duckdb.org) with user-defined
 functions written in TypeScript, served to DuckDB over the **Vector Gateway
@@ -95,6 +111,7 @@ const upperCase = defineScalarFunction({
   },
 
   // Other optional fields: constParams, nullHandling, stability (volatility),
+  // argumentMonotonicity,
   // examples, categories, tags, requiredSettings, requiredSecrets, maxWorkers.
 });
 
@@ -361,6 +378,11 @@ const addHour = defineScalarFunction({
 });
 ```
 
+`argumentMonotonicity` is optional and scalar-only. If supplied, it must have
+one entry per ordered parameter declaration. Fixed, defaulted, and constant
+parameters each use one slot; a vararg declaration uses one slot regardless of
+call-time expansion. Named invocation order does not reorder the metadata.
+
 ```ts
 import {
   Worker, defineScalarFunction, timestampMicros,
@@ -549,6 +571,9 @@ Subpath exports:
 - **`vgi-python`** — the reference implementation. This package is a wire-compatible
   TypeScript port; workers from either side interoperate.
 
+See [Iroh operations](docs/iroh.md) for native Node/Bun and browser clients,
+and identity-preserving worker bridge setup.
+
 ## Development
 
 ```bash

package/dist/arguments/argument-spec.d.ts

@@ -55,9 +55,11 @@ export declare function formatRange(ge?: number, le?: number, gt?: number, lt?:
 /**
  * Encode raw {@link ArgumentConstraints} into the pre-computed constraint
  * fields of an {@link ArgumentSpec} (presence-only — absent constraints yield
- * no field). Mirrors Python's `_constraint_kwargs`.
+ * no field). `runtimeDefault`, when present, is authoritative for
+ * `defaultJson`, keeping runtime binding and discovery metadata in sync.
+ * Mirrors Python's `_constraint_kwargs`.
  */
-export declare function constraintSpecFields(constraints: ArgumentConstraints | undefined): Pick<ArgumentSpec, "defaultJson" | "choicesJson" | "rangeNotation" | "pattern">;
+export declare function constraintSpecFields(constraints: ArgumentConstraints | undefined, runtimeDefault?: unknown): Pick<ArgumentSpec, "defaultJson" | "choicesJson" | "rangeNotation" | "pattern">;
 /**
  * Narrow a bind-time argument value from Arrow's bigint to a plain number.
  *

package/dist/catalog/composite.d.ts

@@ -12,22 +12,22 @@ export declare class CompositeCatalogInterface extends CatalogInterface {
     detach(attachOpaqueData: AttachOpaqueData): Promise<void>;
     version(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Promise<number>;
     schemas(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Promise<SchemaInfo[]>;
-    schemaGet(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<SchemaInfo | null>;
-    schemaContentsTables(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo[]>;
-    schemaContentsViews(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo[]>;
-    schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, name: string, type: string, transactionOpaqueData?: TransactionOpaqueData): Promise<FunctionInfo[]>;
-    schemaContentsMacros(attachOpaqueData: AttachOpaqueData, name: string, type: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo[]>;
-    schemaContentsIndexes(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<IndexInfo[]>;
-    indexGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<IndexInfo | null>;
-    tableGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo | null>;
-    tableScanFunctionGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<any>;
-    tableScanBranchesGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<any>;
-    tableColumnStatisticsGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<{
+    schemaGet(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Promise<SchemaInfo | null>;
+    schemaContentsTables(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo[]>;
+    schemaContentsViews(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo[]>;
+    schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, path: string[], type: string, transactionOpaqueData?: TransactionOpaqueData): Promise<FunctionInfo[]>;
+    schemaContentsMacros(attachOpaqueData: AttachOpaqueData, path: string[], type: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo[]>;
+    schemaContentsIndexes(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Promise<IndexInfo[]>;
+    indexGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<IndexInfo | null>;
+    tableGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo | null>;
+    tableScanFunctionGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<any>;
+    tableScanBranchesGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<any>;
+    tableColumnStatisticsGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<{
         bytes: Uint8Array;
         cacheMaxAgeSeconds: number | null;
     } | null>;
-    viewGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo | null>;
-    macroGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo | null>;
+    viewGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo | null>;
+    macroGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo | null>;
     copyFromFormats(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Promise<CopyFromFormatInfo[]>;
     transactionBegin(attachOpaqueData: AttachOpaqueData): Promise<Uint8Array | null>;
     transactionCommit(attachOpaqueData: AttachOpaqueData, transactionOpaqueData: TransactionOpaqueData): Promise<void>;

package/dist/catalog/descriptors.d.ts

@@ -14,7 +14,7 @@ export interface ForeignKeyDef {
     columns: string[];
     referencedTable: string;
     referencedColumns: string[];
-    referencedSchema?: string;
+    referencedSchemaPath?: string[];
 }
 export type DefaultValue = string | number | boolean | null;
 export interface TableDescriptor {
@@ -129,7 +129,10 @@ export interface IndexDescriptor {
     tags?: Record<string, string>;
 }
 export interface SchemaDescriptor {
-    name: string;
+    /** Raw identifier components, from the catalog root to this schema. */
+    path?: string[];
+    /** @deprecated Protocol 1.x compatibility; prefer `path: [name]`. */
+    name?: string;
     tables?: TableDescriptor[];
     views?: ViewDescriptor[];
     macros?: MacroDescriptor[];
@@ -138,6 +141,7 @@ export interface SchemaDescriptor {
     comment?: string;
     tags?: Record<string, string>;
 }
+export declare function schemaDescriptorPath(schema: SchemaDescriptor): string[];
 export interface SecretTypeDescriptor {
     name: string;
     description: string;
@@ -170,7 +174,7 @@ export interface CatalogDescriptor {
      * records on `catalog_attach.global_functions`.
      *
      * Every entry must also be declared in exactly one of this catalog's
-     * schemas — the `FunctionInfo.schema_name` it carries is the bind-dispatch
+     * schemas — the `FunctionInfo.schema_path` it carries is the bind-dispatch
      * key, not a sentinel. Mirrors vgi-python's `Catalog.global_functions`.
      */
     globalFunctions?: VgiFunction[];

package/dist/catalog/interface.d.ts

@@ -95,10 +95,19 @@ 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 }` that
+ * `{ 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`.
  *
@@ -109,15 +118,19 @@ export interface ScanFunctionResult {
  *
  * `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[]): Uint8Array;
+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;
 /**
@@ -134,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[];
@@ -177,12 +191,25 @@ export interface ScanBranchInput {
     /**
      * 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`
@@ -256,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
@@ -281,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
@@ -309,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

@@ -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";