@query-farm/vgi 0.28.0 → 0.29.1

package/dist/worker.d.ts

@@ -1,6 +1,6 @@
 import { FunctionRegistry } from "./functions/registry.js";
 import type { VgiFunction } from "./functions/types.js";
-import type { CatalogDescriptor } from "./catalog/descriptors.js";
+import { type CatalogDescriptor } from "./catalog/descriptors.js";
 import type { CatalogInterface } from "./catalog/interface.js";
 import { ReadOnlyCatalogInterface } from "./catalog/read-only.js";
 export interface WorkerConfig {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "description": "TypeScript framework for extending DuckDB with user-defined functions via the Vector Gateway Interface (VGI) over Arrow IPC.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Query Farm LLC (https://query.farm)",
@@ -90,12 +90,12 @@
   },
   "peerDependencies": {
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": ">=0.21.0 <0.22.0"
+    "@query-farm/vgi-rpc": ">=0.23.0 <0.24.0"
   },
   "devDependencies": {
     "@duckdb/node-api": "^1.5.5-r.4",
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.21.0",
+    "@query-farm/vgi-rpc": "^0.23.0",
     "@types/bun": "latest",
     "typescript": "^7.0.2"
   },

package/src/arguments/argument-spec.ts

@@ -120,20 +120,28 @@ export function formatRange(
 /**
  * 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 function constraintSpecFields(
   constraints: ArgumentConstraints | undefined,
+  runtimeDefault?: unknown,
 ): Pick<ArgumentSpec, "defaultJson" | "choicesJson" | "rangeNotation" | "pattern"> {
   const fields: Pick<
     ArgumentSpec,
     "defaultJson" | "choicesJson" | "rangeNotation" | "pattern"
   > = {};
-  if (constraints === undefined) return fields;
-
-  if ("default" in constraints && constraints.default !== undefined) {
+  // argDefaults is the runtime source of truth. Surface that same value to
+  // discovery so callers do not have to duplicate it as
+  // argConstraints[name].default. Keep the latter as a backwards-compatible
+  // discovery-only fallback for APIs that do not have a runtime default.
+  if (runtimeDefault !== undefined) {
+    fields.defaultJson = safeJson(runtimeDefault);
+  } else if (constraints !== undefined && "default" in constraints && constraints.default !== undefined) {
     fields.defaultJson = safeJson(constraints.default);
   }
+  if (constraints === undefined) return fields;
   if (constraints.choices !== undefined) {
     fields.choicesJson = safeJson([...constraints.choices]);
   }
@@ -167,6 +175,87 @@ function choiceEquals(choice: unknown, value: unknown): boolean {
   return choice === value;
 }
 
+/**
+ * Narrow a bind-time argument value from Arrow's bigint to a plain number.
+ *
+ * DuckDB types an integer literal as BIGINT, so `series(3)` arrives as `3n`
+ * whether or not anyone wanted 64 bits. Nobody writes `BigInt(1000)` for a page
+ * size, so the arg paths narrow — and they now all narrow the same way, which
+ * they did not before (two sites used safeNumber, two a bare Number).
+ *
+ * This is lossy above 2^53, and that is a deliberate call rather than an
+ * oversight. Every int64 *argument* across the fixtures and every shipped
+ * worker is a small control value — count, page_size, batch_size, increment,
+ * lag_minutes, restatement_lookback_days. The large int64s in the test suite
+ * are all somewhere else entirely:
+ *
+ *   - column data (copy_to/types.test, copy_to/parallel.test) — never touches
+ *     this path;
+ *   - filter-pushdown constants (filter_pushdown/integers.test pins 2^53+1 on
+ *     purpose) — deserialize.ts keeps those bigint, with its own regression
+ *     test;
+ *   - varargs values (constant_columns) — read raw off bindCall.arguments,
+ *     because extractArgs' copy of them is not what the function reads;
+ *   - time-travel versions — carried as strings (`at_value`).
+ *
+ * Preserving the bigint on overflow was tried and reverted: it buys nothing for
+ * any argument that exists, and costs a JS type that depends on magnitude, so a
+ * worker doing `args.n + 1` would work in every test and fail on one caller's
+ * input. If an argument ever genuinely needs the full range — a snowflake id, a
+ * nanosecond epoch — the fix is to make int64 arguments bigint by declared
+ * type, not by magnitude.
+ */
+export function narrowArgValue(value: unknown): unknown {
+  return typeof value === "bigint" ? Number(value) : value;
+}
+
+/**
+ * Reject a type *factory* where an Arrow *type* was expected.
+ *
+ * `params: { n: int64 }` (no parentheses) is accepted by the type system —
+ * `VgiDataType` is loose enough — and then silently produces an ArgumentSpec
+ * whose `arrowType` is a Function. Nothing complains until the schema is
+ * serialized or the bind arrives, and the error at that point names neither the
+ * argument nor the cause.
+ *
+ * The mistake is easy to make on purpose, too: the same identifier is a
+ * ready-made type on one entry point and a factory on another.
+ *
+ *   @query-farm/vgi            int, int32, float32, bool  →  type instances
+ *   @query-farm/vgi/worker-cf  int, int32, float32, bool  →  factories
+ *
+ * So moving a worker to Cloudflare can turn a correct declaration into a
+ * silently wrong one with no other edit. Failing here, at definition time,
+ * makes that a startup error naming the field.
+ */
+export function assertArrowType(value: unknown, where: string): void {
+  if (typeof value === "function") {
+    const name = (value as { name?: string }).name;
+    const call = name ? `${name}()` : "the factory";
+    throw new ArgumentValidationError(
+      `${where} is a type factory, not an Arrow type — call it: ${call}. ` +
+        `(Note that int, int32, float32 and bool are ready-made types on ` +
+        `@query-farm/vgi but factories on @query-farm/vgi/worker-cf, so the ` +
+        `same name may need parentheses on one entry point and not the other. ` +
+        `int64(), float64(), utf8() and the rest are factories everywhere.)`,
+    );
+  }
+  if (value === null || value === undefined) {
+    throw new ArgumentValidationError(`${where} is ${String(value)}, not an Arrow type.`);
+  }
+}
+
+/** {@link assertArrowType} over a record of declared types, e.g. `params`. */
+export function assertArrowTypes(
+  types: Record<string, unknown> | undefined,
+  where: string,
+): void {
+  if (!types) return;
+  for (const [name, type] of Object.entries(types)) {
+    assertArrowType(type, `${where}.${name}`);
+  }
+}
+
 /**
  * Enforce a bind-time const value against its declared {@link ArgumentConstraints},
  * throwing {@link ArgumentValidationError} on violation. Mirrors the Python SDK's

package/src/arguments/arguments.ts

@@ -3,7 +3,6 @@
 // Holds positional and named scalar values from DuckDB.
 
 import type { VgiSchema } from "../arrow/index.js";
-import { safeNumber } from "../util/arrow/index.js";
 
 export class Arguments {
   readonly positional: (any | null)[];

package/src/arrow/impl-arrowjs/index.ts

@@ -17,7 +17,7 @@ export {
   int8, int16, int32, int64,
   uint8, uint16, uint32, uint64,
   float16, float32, float64,
-  utf8, binary, fixedSizeBinary,
+  utf8, largeUtf8, binary, largeBinary, fixedSizeBinary,
   decimal, decimal128, decimal256,
   date, dateDay, dateMillisecond,
   time, timeSecond, timeMillisecond, timeMicrosecond, timeNanosecond,

package/src/arrow/impl-arrowjs/iterate.ts

@@ -151,8 +151,29 @@ export function batchToSecretDict(
 /**
  * Safe number coercion for BigInt values.
  */
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE = -MAX_SAFE;
+
+/**
+ * Narrow a bigint to a number, refusing to do it lossily.
+ *
+ * Arrow int64/uint64 values arrive as bigint. Several bind-time argument paths
+ * want a plain number, and used to get one from a bare `Number(value)` — which
+ * silently rounds above 2^53, so an id or a nanosecond timestamp passed as a
+ * function argument came back subtly wrong with nothing logged anywhere.
+ *
+ * Throwing is the lesser evil: a caller that genuinely wants a lossy narrowing
+ * can still write `Number(v)` themselves, but nobody has to discover the loss
+ * from mismatched output weeks later.
+ */
 export function safeNumber(value: any): number {
   if (typeof value === "bigint") {
+    if (value > MAX_SAFE || value < MIN_SAFE) {
+      throw new RangeError(
+        `${value} cannot be represented exactly as a JS number ` +
+          `(|value| > Number.MAX_SAFE_INTEGER). Keep it as a bigint.`,
+      );
+    }
     return Number(value);
   }
   return value as number;

package/src/arrow/impl-arrowjs/schema.ts

@@ -20,7 +20,9 @@ import {
   Float32 as A_Float32,
   Float64 as A_Float64,
   Utf8 as A_Utf8,
+  LargeUtf8 as A_LargeUtf8,
   Binary as A_Binary,
+  LargeBinary as A_LargeBinary,
   Decimal as A_Decimal,
   Date_ as A_Date,
   Time as A_Time,
@@ -134,7 +136,9 @@ export const float32 = (): VgiDataType => new A_Float32() as unknown as VgiDataT
 export const float64 = (): VgiDataType => new A_Float64() as unknown as VgiDataType;
 
 export const utf8 = (): VgiDataType => new A_Utf8() as unknown as VgiDataType;
+export const largeUtf8 = (): VgiDataType => new A_LargeUtf8() as unknown as VgiDataType;
 export const binary = (): VgiDataType => new A_Binary() as unknown as VgiDataType;
+export const largeBinary = (): VgiDataType => new A_LargeBinary() as unknown as VgiDataType;
 export const fixedSizeBinary = (byteWidth: number): VgiDataType =>
   new A_FixedSizeBinary(byteWidth) as unknown as VgiDataType;
 

package/src/arrow/impl-flechette/index.ts

@@ -22,7 +22,7 @@ export {
   int8, int16, int32, int64,
   uint8, uint16, uint32, uint64,
   float16, float32, float64,
-  utf8, binary, fixedSizeBinary,
+  utf8, largeUtf8, binary, largeBinary, fixedSizeBinary,
   decimal, decimal128, decimal256,
   date, dateDay, dateMillisecond,
   time, timeSecond, timeMillisecond, timeMicrosecond, timeNanosecond,

package/src/arrow/impl-flechette/iterate.ts

@@ -115,7 +115,30 @@ export function batchToSecretDict(
 /**
  * BigInt → number coercion (lossy for values past 2^53).
  */
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE = -MAX_SAFE;
+
+/**
+ * Narrow a bigint to a number, refusing to do it lossily.
+ *
+ * Arrow int64/uint64 values arrive as bigint. Several bind-time argument paths
+ * want a plain number, and used to get one from a bare `Number(value)` — which
+ * silently rounds above 2^53, so an id or a nanosecond timestamp passed as a
+ * function argument came back subtly wrong with nothing logged anywhere.
+ *
+ * Throwing is the lesser evil: a caller that genuinely wants a lossy narrowing
+ * can still write `Number(v)` themselves, but nobody has to discover the loss
+ * from mismatched output weeks later.
+ */
 export function safeNumber(value: any): number {
-  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "bigint") {
+    if (value > MAX_SAFE || value < MIN_SAFE) {
+      throw new RangeError(
+        `${value} cannot be represented exactly as a JS number ` +
+          `(|value| > Number.MAX_SAFE_INTEGER). Keep it as a bigint.`,
+      );
+    }
+    return Number(value);
+  }
   return value as number;
 }

package/src/arrow/impl-flechette/schema.ts

@@ -23,7 +23,9 @@ import {
   float32 as f_float32,
   float64 as f_float64,
   utf8 as f_utf8,
+  largeUtf8 as f_largeUtf8,
   binary as f_binary,
+  largeBinary as f_largeBinary,
   fixedSizeBinary as f_fixedSizeBinary,
   decimal as f_decimal,
   decimal128 as f_decimal128,
@@ -111,7 +113,9 @@ export const float32 = (): VgiDataType => f_float32() as unknown as VgiDataType;
 export const float64 = (): VgiDataType => f_float64() as unknown as VgiDataType;
 
 export const utf8 = (): VgiDataType => f_utf8() as unknown as VgiDataType;
+export const largeUtf8 = (): VgiDataType => f_largeUtf8() as unknown as VgiDataType;
 export const binary = (): VgiDataType => f_binary() as unknown as VgiDataType;
+export const largeBinary = (): VgiDataType => f_largeBinary() as unknown as VgiDataType;
 export const fixedSizeBinary = (stride: number): VgiDataType =>
   f_fixedSizeBinary(stride) as unknown as VgiDataType;
 

package/src/arrow/index.ts

@@ -81,7 +81,7 @@ export {
   int, int8, int16, int32, int64,
   uint8, uint16, uint32, uint64,
   float16, float32, float64,
-  utf8, binary, fixedSizeBinary,
+  utf8, largeUtf8, binary, largeBinary, fixedSizeBinary,
   decimal, decimal128, decimal256,
   date, dateDay, dateMillisecond,
   time, timeSecond, timeMillisecond, timeMicrosecond, timeNanosecond,

package/src/arrow/schema-types.ts

@@ -25,7 +25,9 @@ import type {
   IntType,
   FloatType,
   Utf8Type,
+  LargeUtf8Type,
   BinaryType,
+  LargeBinaryType,
   FixedSizeBinaryType,
   DecimalType,
   Date32Type, Date64Type,
@@ -83,7 +85,9 @@ export const float32 = (): FloatType => impl.float32() as unknown as FloatType;
 export const float64 = (): FloatType => impl.float64() as unknown as FloatType;
 
 export const utf8 = (): Utf8Type => impl.utf8() as unknown as Utf8Type;
+export const largeUtf8 = (): LargeUtf8Type => impl.largeUtf8() as unknown as LargeUtf8Type;
 export const binary = (): BinaryType => impl.binary() as unknown as BinaryType;
+export const largeBinary = (): LargeBinaryType => impl.largeBinary() as unknown as LargeBinaryType;
 export const fixedSizeBinary = (byteWidth: number): FixedSizeBinaryType =>
   impl.fixedSizeBinary(byteWidth) as unknown as FixedSizeBinaryType;
 

package/src/arrow/types.ts

@@ -33,9 +33,43 @@ export interface VgiSchema {
   readonly metadata: Map<string, string>;
 }
 
-/** Column view. Generic dropped: arrow-js parameterizes on DataType, flechette
- *  on value type, so the facade exposes an erased shape. Callers cast at the
- *  use site (the column's static schema makes the value type known there). */
+/**
+ * Column view over one column of a batch.
+ *
+ * The value type is erased by default: arrow-js parameterizes on DataType and
+ * flechette on value type, so the facade cannot name one without picking a
+ * backend. Supply `T` at the use site — the column's declared type makes it
+ * known there — and the cast disappears:
+ *
+ * ```ts
+ * const ns = batch.getChildAt(0)! as Iterable<bigint | null>;
+ * for (const v of ns) { ... }        // v: bigint | null
+ * ```
+ *
+ * A type parameter here would read better, but it cannot be had cheaply: both
+ * backends' native batches are assigned to VgiBatch structurally, and a
+ * concrete `get(): unknown` does not satisfy a generic `get(): T`. Adding one
+ * would mean casting at ~25 internal sites to remove one cast in user code.
+ *
+ * **These are the backend's own values, not codec output.** `get()` and
+ * iteration return whatever the Arrow implementation stores, which for some
+ * types is not the value the SDK documents:
+ *
+ * | Arrow type       | here                          | {@link iterRows}      |
+ * | ---------------- | ----------------------------- | --------------------- |
+ * | `int64`          | `bigint`                      | `bigint`   (same)     |
+ * | `utf8`, `float64`| `string`, `number`            | same                  |
+ * | `decimal128`     | backend limbs (`DecimalBigNum`)| `bigint`, unscaled    |
+ * | `timestamp[us]`  | millisecond `number`          | microsecond `bigint`  |
+ * | `date32`         | millisecond `number`          | `Date`                |
+ *
+ * `repr: "raw"` on a function selects the *codec's* representation and has no
+ * effect on this path.
+ *
+ * So: reach for `getChildAt` on integer, float, boolean, string and binary
+ * columns, where it is the cheapest correct thing. For temporal, decimal and
+ * nested types go through {@link iterRows}, which runs the codec.
+ */
 export interface VgiColumn {
   readonly type: VgiDataType;
   readonly length: number;
@@ -46,7 +80,9 @@ export interface VgiColumn {
 export interface VgiBatch {
   readonly schema: VgiSchema;
   readonly numRows: number;
+  /** See {@link VgiColumn} — this does NOT run the codec. */
   getChild(name: string): VgiColumn | null;
+  /** See {@link VgiColumn} — this does NOT run the codec. */
   getChildAt(index: number): VgiColumn | null;
 }
 

package/src/catalog/composite.ts

@@ -119,56 +119,56 @@ export class CompositeCatalogInterface extends CatalogInterface {
     return await this._route(attachOpaqueData).schemas(attachOpaqueData, transactionOpaqueData);
   }
 
-  override async schemaGet(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<SchemaInfo | null> {
-    return await this._route(attachOpaqueData).schemaGet(attachOpaqueData, name, transactionOpaqueData);
+  override async schemaGet(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Promise<SchemaInfo | null> {
+    return await this._route(attachOpaqueData).schemaGet(attachOpaqueData, path, transactionOpaqueData);
   }
 
-  override async schemaContentsTables(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo[]> {
-    return await this._route(attachOpaqueData).schemaContentsTables(attachOpaqueData, name, transactionOpaqueData);
+  override async schemaContentsTables(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo[]> {
+    return await this._route(attachOpaqueData).schemaContentsTables(attachOpaqueData, path, transactionOpaqueData);
   }
 
-  override async schemaContentsViews(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo[]> {
-    return await this._route(attachOpaqueData).schemaContentsViews(attachOpaqueData, name, transactionOpaqueData);
+  override async schemaContentsViews(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo[]> {
+    return await this._route(attachOpaqueData).schemaContentsViews(attachOpaqueData, path, transactionOpaqueData);
   }
 
-  override async schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, name: string, type: string, transactionOpaqueData?: TransactionOpaqueData): Promise<FunctionInfo[]> {
-    return await this._route(attachOpaqueData).schemaContentsFunctions(attachOpaqueData, name, type, transactionOpaqueData);
+  override async schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, path: string[], type: string, transactionOpaqueData?: TransactionOpaqueData): Promise<FunctionInfo[]> {
+    return await this._route(attachOpaqueData).schemaContentsFunctions(attachOpaqueData, path, type, transactionOpaqueData);
   }
 
-  override async schemaContentsMacros(attachOpaqueData: AttachOpaqueData, name: string, type: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo[]> {
-    return await this._route(attachOpaqueData).schemaContentsMacros(attachOpaqueData, name, type, transactionOpaqueData);
+  override async schemaContentsMacros(attachOpaqueData: AttachOpaqueData, path: string[], type: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo[]> {
+    return await this._route(attachOpaqueData).schemaContentsMacros(attachOpaqueData, path, type, transactionOpaqueData);
   }
 
-  override async schemaContentsIndexes(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<IndexInfo[]> {
-    return await this._route(attachOpaqueData).schemaContentsIndexes(attachOpaqueData, name, transactionOpaqueData);
+  override async schemaContentsIndexes(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): Promise<IndexInfo[]> {
+    return await this._route(attachOpaqueData).schemaContentsIndexes(attachOpaqueData, path, transactionOpaqueData);
   }
 
-  override async indexGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<IndexInfo | null> {
-    return await this._route(attachOpaqueData).indexGet(attachOpaqueData, schemaName, name, transactionOpaqueData);
+  override async indexGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<IndexInfo | null> {
+    return await this._route(attachOpaqueData).indexGet(attachOpaqueData, schemaPath, name, transactionOpaqueData);
   }
 
-  override async tableGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo | null> {
-    return await this._route(attachOpaqueData).tableGet(attachOpaqueData, schemaName, name, atUnit, atValue, transactionOpaqueData);
+  override async tableGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo | null> {
+    return await this._route(attachOpaqueData).tableGet(attachOpaqueData, schemaPath, name, atUnit, atValue, transactionOpaqueData);
   }
 
-  override async tableScanFunctionGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<any> {
-    return await this._route(attachOpaqueData).tableScanFunctionGet(attachOpaqueData, schemaName, name, atUnit, atValue, transactionOpaqueData);
+  override async tableScanFunctionGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<any> {
+    return await this._route(attachOpaqueData).tableScanFunctionGet(attachOpaqueData, schemaPath, name, atUnit, atValue, transactionOpaqueData);
   }
 
-  override async tableScanBranchesGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<any> {
-    return await this._route(attachOpaqueData).tableScanBranchesGet(attachOpaqueData, schemaName, name, atUnit, atValue, transactionOpaqueData);
+  override async tableScanBranchesGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<any> {
+    return await this._route(attachOpaqueData).tableScanBranchesGet(attachOpaqueData, schemaPath, name, atUnit, atValue, transactionOpaqueData);
   }
 
-  override async tableColumnStatisticsGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<{ bytes: Uint8Array; cacheMaxAgeSeconds: number | null } | null> {
-    return await this._route(attachOpaqueData).tableColumnStatisticsGet(attachOpaqueData, schemaName, name, transactionOpaqueData);
+  override async tableColumnStatisticsGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<{ bytes: Uint8Array; cacheMaxAgeSeconds: number | null } | null> {
+    return await this._route(attachOpaqueData).tableColumnStatisticsGet(attachOpaqueData, schemaPath, name, transactionOpaqueData);
   }
 
-  override async viewGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo | null> {
-    return await this._route(attachOpaqueData).viewGet(attachOpaqueData, schemaName, name, transactionOpaqueData);
+  override async viewGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo | null> {
+    return await this._route(attachOpaqueData).viewGet(attachOpaqueData, schemaPath, name, transactionOpaqueData);
   }
 
-  override async macroGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo | null> {
-    return await this._route(attachOpaqueData).macroGet(attachOpaqueData, schemaName, name, transactionOpaqueData);
+  override async macroGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo | null> {
+    return await this._route(attachOpaqueData).macroGet(attachOpaqueData, schemaPath, name, transactionOpaqueData);
   }
 
   override async copyFromFormats(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Promise<CopyFromFormatInfo[]> {

package/src/catalog/descriptors.ts

@@ -19,7 +19,7 @@ export interface ForeignKeyDef {
   columns: string[];
   referencedTable: string;
   referencedColumns: string[];
-  referencedSchema?: string;
+  referencedSchemaPath?: string[];
 }
 
 export type DefaultValue = string | number | boolean | null;
@@ -137,7 +137,10 @@ export interface IndexDescriptor {
 }
 
 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[];
@@ -147,6 +150,12 @@ export interface SchemaDescriptor {
   tags?: Record<string, string>;
 }
 
+export function schemaDescriptorPath(schema: SchemaDescriptor): string[] {
+  if (schema.path) return schema.path;
+  if (schema.name) return [schema.name];
+  throw new Error("SchemaDescriptor requires a non-empty path");
+}
+
 export interface SecretTypeDescriptor {
   name: string;
   description: string;
@@ -180,7 +189,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[];