@query-farm/vgi 0.29.0 → 0.29.1

package/src/protocol/handlers/function.ts

@@ -173,7 +173,7 @@ async function resolveSplitPayloads(
   if (!request.split_tokens) return;
   const fp = fingerprintInputs(toUint8Array(innerParams.bind_call));
   const expected = await bindFingerprint(
-    fp.schemaName,
+    fp.schemaPath,
     fp.functionName,
     fp.args,
     fp.settings,
@@ -517,7 +517,7 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
       // layout can change without touching worker code in five languages.
       const fp = fingerprintInputs(toUint8Array(innerParams.bind_call));
       const fingerprint = await bindFingerprint(
-        fp.schemaName,
+        fp.schemaPath,
         fp.functionName,
         fp.args,
         fp.settings,

package/src/protocol/handlers/shared.ts

@@ -7,6 +7,7 @@ import { batchToScalarDict, deserializeBatch, serializeBatch, batchFromColumns }
 import { toUint8Array } from "../../util/bytes.js";
 import { TableInOutPhase } from "../../types.js";
 import type { InitRequest } from "../types.js";
+import { normalizeSchemaPath } from "../../schema-path.js";
 
 // The Python vgi-rpc framework wraps ALL non-void unary results in a single
 // "result" column. For ArrowSerializableDataclass types, the result is serialized
@@ -31,7 +32,15 @@ export const RESULT_BINARY_NULLABLE_SCHEMA = schema([
 export function unwrapRequest(requestBytes: any): Record<string, any> {
   const bytes = toUint8Array(requestBytes);
   const innerBatch = deserializeBatch(bytes);
-  return batchToScalarDict(innerBatch);
+  const params = batchToScalarDict(innerBatch);
+  normalizeRequestSchemaPaths(params);
+  return params;
+}
+
+/** Convert Arrow list scalars at RPC boundaries into ordinary string arrays. */
+export function normalizeRequestSchemaPaths(params: Record<string, any>): void {
+  if (params.path != null) params.path = normalizeSchemaPath(params.path);
+  if (params.schema_path != null) params.schema_path = normalizeSchemaPath(params.schema_path);
 }
 
 /**
@@ -57,7 +66,7 @@ export function overloadContext(
     arguments: any;
     input_schema: any;
     function_type: any;
-    schema_name?: string | null;
+    schema_path?: string[] | null;
     attach_opaque_data?: Uint8Array | null;
   },
   catalogInterface?: { catalogNameForAttach(a: Uint8Array): string | null },
@@ -78,7 +87,7 @@ export function overloadContext(
     isScalar: String(req.function_type).toLowerCase() === "scalar",
     // Scopes resolution when the caller named a schema; a name registered in
     // several schemas is otherwise ambiguous.
-    schemaName: req.schema_name ?? null,
+    schemaPath: req.schema_path ?? null,
     catalogName,
   };
 }

package/src/protocol/handlers/table-buffering.ts

@@ -46,19 +46,19 @@ export function registerTableBufferingMethods(
   registry: FunctionRegistry,
   signingKey?: Uint8Array,
 ): void {
-  // `schemaName` scopes resolution to the schema the caller named. The
+  // `schemaPath` scopes resolution to the schema the caller named. The
   // buffering process/combine RPCs carry it (protocol 1.2.0), so a name
   // declared in two schemas resolves to the one the request names rather than
   // colliding on the flat by-name index. `null` keeps the cross-schema lookup.
   function resolveBuffering(
     name: string,
-    schemaName?: string | null,
+    schemaPath?: string[] | null,
   ): TableBufferingVgiFunction {
     const func = registry.get(name, {
       arguments: new Arguments(),
       inputSchema: null,
       isScalar: false,
-      schemaName: schemaName ?? null,
+      schemaPath: schemaPath ?? null,
     }) as any;
     if (!func || func.kind !== "table_buffering") {
       throw new Error(`Function '${name}' is not a table_buffering function`);
@@ -86,7 +86,7 @@ export function registerTableBufferingMethods(
         : rawAttach;
     const transactionId = inner.transaction_id ? toUint8Array(inner.transaction_id) : null;
 
-    const func = resolveBuffering(functionName, inner.schema_name ?? null);
+    const func = resolveBuffering(functionName, inner.schema_path ?? null);
     const bound = new BoundStorage(defaultStorage, executionId);
     const payload = await bound.stateGet(
       FrameworkNS.BUFFERING_INIT,

package/src/protocol/serializers/bind.ts

@@ -3,7 +3,7 @@
 // ArrowSerializableDataclass field declaration order so the format is
 // positional-compatible with the Python reader.
 
-import { type VgiSchema, schema, field, type VgiBatch, type VgiDataType, utf8, binary, bool, struct, dictionary, int16 } from "../../arrow/index.js";
+import { type VgiSchema, schema, field, type VgiBatch, type VgiDataType, utf8, binary, bool, struct, dictionary, int16, list } from "../../arrow/index.js";
 import { Arguments } from "../../arguments/arguments.js";
 import { FunctionType } from "../../types.js";
 import type { BindRequest, BindResponse, CopyFromContext, CopyToContext } from "../types.js";
@@ -31,7 +31,7 @@ import { serializeArguments, deserializeArguments } from "./arguments.js";
 // two schemas in full and leaves the reader to diff them by eye.
 //
 // So `copy_from` and `copy_to` are always present and null on a non-COPY bind,
-// `schema_name` is LAST (not before them), and `function_type` is a dictionary
+// `schema_path` and `argument_names` are last, and `function_type` is a dictionary
 // rather than plain utf8.
 const COPY_FROM_STRUCT_TYPE = struct([
   field("format", utf8(), false),
@@ -62,8 +62,10 @@ const BIND_REQUEST_SCHEMA = schema([
   field("copy_to", COPY_TO_STRUCT_TYPE, true),
   // Catalog schema owning the function. A worker may register one name in
   // several schemas, so the bare name is not a unique key — resolution is by
-  // (schema_name, function_name). Null for callers with no catalog context.
-  field("schema_name", utf8(), true),
+  // (schema_path, function_name). Null for callers with no catalog context.
+  field("schema_path", list(field("item", utf8(), true)), true),
+  // Complete resolved logical signature, including const args and varargs.
+  field("argument_names", list(field("item", utf8(), true)), true),
 ]);
 
 export function serializeBindRequest(req: BindRequest): VgiBatch {
@@ -89,7 +91,8 @@ export function serializeBindRequest(req: BindRequest): VgiBatch {
     copy_to: req.copy_to
       ? { format: req.copy_to.format, file_path: req.copy_to.file_path }
       : null,
-    schema_name: req.schema_name ?? null,
+    schema_path: req.schema_path ?? null,
+    argument_names: req.argument_names ?? null,
   });
 }
 
@@ -164,7 +167,13 @@ export function deserializeBindRequest(
     at_unit: params.at_unit ? String(params.at_unit) : null,
     at_value: params.at_value ? String(params.at_value) : null,
     // Empty string -> null, same convention as at_unit/at_value.
-    schema_name: params.schema_name ? String(params.schema_name) : null,
+    schema_path: params.schema_path
+      ? (Array.isArray(params.schema_path) ? params.schema_path : [...params.schema_path]).map(String)
+      : null,
+    argument_names: params.argument_names
+      ? (Array.isArray(params.argument_names) ? params.argument_names : [...params.argument_names])
+        .map((value: unknown) => value == null ? null : String(value))
+      : null,
     // COPY ... FROM context — absent for ordinary scans (params.copy_from
     // undefined -> null). The struct column decodes to a plain object.
     copy_from: parseCopyFromContext(params.copy_from),

package/src/protocol/serializers/splits.ts

@@ -158,14 +158,16 @@ export function deserializePlanRequest(params: Record<string, any>): TableFuncti
  * bytes are.
  */
 export function fingerprintInputs(bindCallBytes: Uint8Array): {
-  schemaName: string;
+  schemaPath: string[];
   functionName: string;
   args: Uint8Array;
   settings: Uint8Array;
 } {
   const dict = batchToScalarDict(deserializeBatch(bindCallBytes));
   return {
-    schemaName: dict.schema_name == null ? "" : String(dict.schema_name),
+    schemaPath: dict.schema_path == null
+      ? []
+      : (Array.isArray(dict.schema_path) ? dict.schema_path : [...dict.schema_path]).map(String),
     functionName: String(dict.function_name ?? ""),
     args: dict.arguments ? toUint8Array(dict.arguments) : new Uint8Array(0),
     settings: dict.settings ? toUint8Array(dict.settings) : new Uint8Array(0),

package/src/protocol/types.ts

@@ -91,11 +91,17 @@ export interface BindRequest {
   /**
    * Catalog schema that declares the function being bound. A worker may
    * register the same name in more than one schema, so the bare name does not
-   * identify an implementation — resolution is by `(schema_name,
+   * identify an implementation — resolution is by `(schema_path,
    * function_name)`. Null for callers with no catalog context (COPY handler
-   * binds). Mirrors vgi-python's `BindRequest.schema_name`.
+   * binds). Mirrors vgi-python's `BindRequest.schema_path`.
    */
-  schema_name?: string | null;
+  schema_path?: string[] | null;
+  /**
+   * Resolved name for every logical argument, in complete call order. Fixed
+   * parameters carry their declared names, unnamed varargs carry `null`, and
+   * named varargs retain the caller-provided name. `null` means unavailable.
+   */
+  argument_names?: (string | null)[] | null;
 }
 
 export interface BindResponse {

package/src/schema-path.ts

@@ -0,0 +1,25 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+/** Raw identifier components of a catalog schema, from root to leaf. */
+export type SchemaPath = string[];
+
+/** Case-insensitive key used for catalog lookup and function dispatch. */
+export function normalizeSchemaPath(path: Iterable<unknown> | string): string[] {
+  return typeof path === "string" ? [path] : Array.from(path, String);
+}
+
+export function schemaPathKey(path: Iterable<unknown> | string): string {
+  const normalized = normalizeSchemaPath(path);
+  if (normalized.length === 0 || normalized.some((part) => part.length === 0)) {
+    throw new Error("schema paths must contain at least one non-empty component");
+  }
+  return normalized.map((part) => part.toLowerCase()).join("\u0000");
+}
+
+export function schemaPathsEqual(left: Iterable<unknown> | string, right: Iterable<unknown> | string): boolean {
+  return schemaPathKey(left) === schemaPathKey(right);
+}
+
+export function schemaPathDisplay(path: Iterable<unknown> | string): string {
+  return normalizeSchemaPath(path).map((part) => JSON.stringify(part)).join(".");
+}

package/src/serve-entry.ts

@@ -23,7 +23,14 @@
 
 import type { CatalogInterface } from "./catalog/interface.js";
 import type { FunctionRegistry } from "./functions/registry.js";
-import type { AuthenticateFn } from "@query-farm/vgi-rpc";
+import {
+  irohForwardedHeaderIdentityProvider,
+  IROH_FORWARDED_ENDPOINT_HEADER,
+  observePeerIdentity,
+  peerIdentityPrimary,
+  type AuthenticateFn,
+  type PeerResolutionOptions,
+} from "@query-farm/vgi-rpc";
 import { createVgiFetch } from "./http/fetch.js";
 
 /** Environment variables `serveVgiWorker` reads. Injectable for testing. */
@@ -39,6 +46,21 @@ export const DEFAULT_TOKEN_TTL = 3600;
 /** Bytes of HMAC key `createHttpHandler` expects; 64 hex characters. */
 export const SIGNING_KEY_BYTES = 32;
 
+/** HTTP trust boundary for a colocated `vgi-iroh-bridge`. */
+export interface IrohHttpBridgeOptions {
+  /** Worker-local namespace for EndpointId principals. */
+  issuer: string;
+  /** Exact bridge IP addresses. No CIDRs or hostnames. */
+  trustedProxyAddresses?: readonly string[];
+  /** Authenticate the EndpointId (default) or expose evidence only. */
+  authenticate?: boolean;
+  /**
+   * Host-specific physical peer and raw-header adapter. Required because a
+   * Fetch Request alone does not preserve duplicate header fields.
+   */
+  peerResolutionContext?: (request: Request) => PeerResolutionOptions | Promise<PeerResolutionOptions>;
+}
+
 export interface ServeVgiWorkerOptions {
   /** Short worker name shown on the landing page, e.g. "ishares". */
   name: string;
@@ -55,6 +77,8 @@ export interface ServeVgiWorkerOptions {
   repositoryUrl?: string;
   /** Overrides `$PORT` (default 8787). Pass 0 to bind an ephemeral port. */
   port?: number;
+  /** Bind address. Iroh bridge mode defaults to loopback; otherwise Bun's default. */
+  hostname?: string;
   /** Overrides `$VGI_SIGNING_KEY`. 32 bytes. */
   signingKey?: Uint8Array;
   /** Overrides `$VGI_TOKEN_TTL` (default 3600 seconds). */
@@ -72,6 +96,8 @@ export interface ServeVgiWorkerOptions {
   /** Authenticates each request, returning the caller's `AuthContext`.
    *  Omit for an anonymous worker (the default). */
   authenticate?: AuthenticateFn;
+  /** Preserve authenticated Iroh identity forwarded by an adjacent HTTP bridge. */
+  irohBridge?: IrohHttpBridgeOptions;
 }
 
 /** The slice of `Bun.serve`'s return value this module uses. */
@@ -79,11 +105,13 @@ export interface VgiHttpServer {
   readonly port: number;
   readonly url: URL;
   stop(closeActiveConnections?: boolean): void;
+  requestIP?(request: Request): { address: string } | null;
 }
 
 interface BunLike {
   serve(options: {
     port: number;
+    hostname?: string;
     fetch: (req: Request) => Promise<Response>;
   }): VgiHttpServer;
 }
@@ -188,6 +216,13 @@ export function createVgiWorkerFetch(
   // mean "off" would silently re-enable it. `undefined` falls through to the env
   // var and then to that same default.
   const corsOrigins = opts.corsOrigins === null ? null : (opts.corsOrigins ?? env.CORS_ORIGINS);
+  const bridge = opts.irohBridge;
+  if (bridge && !bridge.peerResolutionContext) {
+    throw new Error(
+      "irohBridge requires a peerResolutionContext when createVgiWorkerFetch is used without serveVgiWorker",
+    );
+  }
+  const trustedProxyAddresses = bridge?.trustedProxyAddresses ?? ["127.0.0.1"];
 
   return createVgiFetch({
     protocol: { registry: opts.registry, catalogInterface: opts.catalogInterface },
@@ -199,6 +234,13 @@ export function createVgiWorkerFetch(
     repositoryUrl: opts.repositoryUrl,
     landingInfo: { name: opts.name, doc: opts.doc, version: opts.version },
     authenticate: opts.authenticate,
+    peerIdentityProviders: bridge
+      ? [irohForwardedHeaderIdentityProvider({ issuer: bridge.issuer, trustedProxyAddresses })]
+      : undefined,
+    peerAuthenticationPolicy: bridge
+      ? (bridge.authenticate === false ? observePeerIdentity : peerIdentityPrimary("iroh"))
+      : undefined,
+    peerResolutionContext: bridge?.peerResolutionContext,
   });
 }
 
@@ -220,8 +262,28 @@ export function serveVgiWorker(opts: ServeVgiWorkerOptions): VgiHttpServer {
 
   const env = opts.env ?? (process.env as ServeEnv);
   const port = resolvePort(opts.port, env);
-  const fetch = createVgiWorkerFetch(opts);
-  const server = runtime.serve({ port, fetch });
+  const hostname = opts.hostname ?? (opts.irohBridge ? "127.0.0.1" : undefined);
+  if (opts.irohBridge && !["127.0.0.1", "::1", "localhost"].includes(hostname ?? "")) {
+    throw new Error("an Iroh HTTP bridge upstream must bind loopback");
+  }
+  let server: VgiHttpServer;
+  const bridge = opts.irohBridge && !opts.irohBridge.peerResolutionContext
+    ? {
+        ...opts.irohBridge,
+        peerResolutionContext(request: Request): PeerResolutionOptions {
+          const immediatePeer = server.requestIP?.(request)?.address;
+          const forwarded = request.headers.get(IROH_FORWARDED_ENDPOINT_HEADER);
+          return {
+            immediatePeer,
+            headers: forwarded === null
+              ? {}
+              : { [IROH_FORWARDED_ENDPOINT_HEADER]: [forwarded] },
+          };
+        },
+      }
+    : opts.irohBridge;
+  const fetch = createVgiWorkerFetch({ ...opts, irohBridge: bridge });
+  server = runtime.serve({ port, hostname, fetch });
 
   if (!opts.quiet) {
     const base = `http://localhost:${server.port}`;

package/src/split-token.ts

@@ -112,7 +112,7 @@ function equalBytes(a: Uint8Array, b: Uint8Array): boolean {
  * browser and Cloudflare Workers builds.
  */
 export async function bindFingerprint(
-  schemaName: string,
+  schemaPath: string[],
   functionName: string,
   args: Uint8Array,
   settings: Uint8Array,
@@ -123,7 +123,7 @@ export async function bindFingerprint(
   const field = (label: string, value: Uint8Array) => concat(enc.encode(label), zero, value, zero);
   const message = concat(
     AAD_PREFIX,
-    field("schema_name", enc.encode(schemaName)),
+    field("schema_path", enc.encode(JSON.stringify(schemaPath))),
     field("function_name", enc.encode(functionName)),
     field("arguments", args),
     field("settings", settings),

package/src/types.ts

@@ -22,6 +22,15 @@ export enum NullHandling {
   SPECIAL = "SPECIAL",
 }
 
+export enum ArgumentMonotonicity {
+  UNKNOWN = "UNKNOWN",
+  CONSTANT = "CONSTANT",
+  NON_DECREASING = "NON_DECREASING",
+  STRICTLY_INCREASING = "STRICTLY_INCREASING",
+  NON_INCREASING = "NON_INCREASING",
+  STRICTLY_DECREASING = "STRICTLY_DECREASING",
+}
+
 export enum OrderPreservation {
   /** Output rows are in same order as input rows (DuckDB INSERTION_ORDER). */
   PRESERVES_ORDER = "PRESERVES_ORDER",

package/src/worker.ts

@@ -1,12 +1,19 @@
 // Copyright 2025, 2026 Query Farm LLC - https://query.farm
 // VGI Worker: main entry point for running a VGI function server.
 
-import { VgiRpcServer, serveUnix, serveTcp, serveStream as serveStreamRpc } from "@query-farm/vgi-rpc";
+import {
+  VgiRpcServer,
+  observePeerIdentity,
+  peerIdentityPrimary,
+  serveUnix,
+  serveTcp,
+  serveStream as serveStreamRpc,
+} from "@query-farm/vgi-rpc";
 import { FunctionRegistry } from "./functions/registry.js";
 import type { VgiFunction } from "./functions/types.js";
 import { buildVgiProtocol } from "./protocol/dispatch.js";
 import type { Protocol } from "@query-farm/vgi-rpc";
-import type { CatalogDescriptor } from "./catalog/descriptors.js";
+import { schemaDescriptorPath, type CatalogDescriptor } from "./catalog/descriptors.js";
 import type { CatalogInterface } from "./catalog/interface.js";
 import { ReadOnlyCatalogInterface } from "./catalog/read-only.js";
 
@@ -41,6 +48,10 @@ interface LauncherArgs {
   /** TCP bind port; present iff `--tcp` was passed. */
   tcpPort?: number;
   idleTimeout?: number;
+  irohRawUpstream?: boolean;
+  irohIssuer?: string;
+  irohTrustedProxyAddresses: string[];
+  irohAuthenticate: boolean;
 }
 
 // Parse a `[HOST:]PORT` --tcp bind spec into a LauncherArgs. A bare PORT (no
@@ -58,7 +69,7 @@ function parseTcpSpec(spec: string, out: LauncherArgs): void {
 }
 
 function parseLauncherArgs(argv: readonly string[]): LauncherArgs {
-  const out: LauncherArgs = {};
+  const out: LauncherArgs = { irohTrustedProxyAddresses: [], irohAuthenticate: true };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--unix" && i + 1 < argv.length) {
@@ -73,6 +84,22 @@ function parseLauncherArgs(argv: readonly string[]): LauncherArgs {
       out.idleTimeout = Number(argv[++i]);
     } else if (a.startsWith("--idle-timeout=")) {
       out.idleTimeout = Number(a.slice("--idle-timeout=".length));
+    } else if (a === "--iroh-raw-upstream" && i + 1 < argv.length) {
+      parseTcpSpec(argv[++i], out);
+      out.irohRawUpstream = true;
+    } else if (a.startsWith("--iroh-raw-upstream=")) {
+      parseTcpSpec(a.slice("--iroh-raw-upstream=".length), out);
+      out.irohRawUpstream = true;
+    } else if (a === "--iroh-issuer" && i + 1 < argv.length) {
+      out.irohIssuer = argv[++i];
+    } else if (a.startsWith("--iroh-issuer=")) {
+      out.irohIssuer = a.slice("--iroh-issuer=".length);
+    } else if (a === "--iroh-trusted-proxy" && i + 1 < argv.length) {
+      out.irohTrustedProxyAddresses.push(...argv[++i].split(",").filter(Boolean));
+    } else if (a.startsWith("--iroh-trusted-proxy=")) {
+      out.irohTrustedProxyAddresses.push(...a.slice("--iroh-trusted-proxy=".length).split(",").filter(Boolean));
+    } else if (a === "--iroh-observe") {
+      out.irohAuthenticate = false;
     }
   }
   return out;
@@ -122,7 +149,7 @@ export class Worker {
             this._registry.register(func);
             // Also index by owning schema + catalog so a schema-qualified bind
             // resolves when one name is declared in more than one schema.
-            this._registry.registerInSchema(func, schema.name, config.catalog.name);
+            this._registry.registerInSchema(func, schemaDescriptorPath(schema), config.catalog.name);
           }
         }
       }
@@ -149,6 +176,12 @@ export class Worker {
       debug(() => `[worker] protocol built`);
 
       const launcher = parseLauncherArgs(argv);
+      if (launcher.irohRawUpstream) {
+        if (!launcher.irohIssuer) throw new TypeError("--iroh-raw-upstream requires --iroh-issuer");
+        if (!["127.0.0.1", "::1", "localhost"].includes(launcher.tcpHost ?? "")) {
+          throw new TypeError("--iroh-raw-upstream must bind loopback");
+        }
+      }
       if (launcher.unixPath !== undefined) {
         // VGI_WORKER_IDLE_TIMEOUT overrides whatever the C++ launcher
         // appended via --idle-timeout. Useful in test setups where the
@@ -191,6 +224,18 @@ export class Worker {
           host: launcher.tcpHost,
           port: launcher.tcpPort,
           idleTimeout,
+          ...(launcher.irohRawUpstream
+            ? {
+                proxyProtocolV2Required: true,
+                trustedProxyAddresses: launcher.irohTrustedProxyAddresses.length > 0
+                  ? launcher.irohTrustedProxyAddresses
+                  : ["127.0.0.1"],
+                irohProxyIssuer: launcher.irohIssuer,
+                peerAuthenticationPolicy: launcher.irohAuthenticate
+                  ? peerIdentityPrimary("iroh")
+                  : observePeerIdentity,
+              }
+            : {}),
         }).then((handle) => handle.done).then(() => {
           debug(() => `[worker] serveTcp done (idle shutdown)`);
         }).catch((err: any) => {