@query-farm/vgi 0.21.0 → 0.22.0

package/dist/worker.d.ts

@@ -1,3 +1,4 @@
+import { FunctionRegistry } from "./functions/registry.js";
 import type { VgiFunction } from "./functions/types.js";
 import type { CatalogDescriptor } from "./catalog/descriptors.js";
 import type { CatalogInterface } from "./catalog/interface.js";
@@ -9,6 +10,14 @@ export interface WorkerConfig {
     /** Factory that receives the built ReadOnlyCatalogInterface and returns a custom catalog. */
     catalogInterfaceFactory?: (base: ReadOnlyCatalogInterface) => CatalogInterface;
     catalogName?: string;
+    /**
+     * Registry to dispatch through. Pass the same instance used to build a
+     * pre-constructed `catalogInterface` — catalogs record which schema (and
+     * catalog) declares each function on the registry they are given, and
+     * schema-qualified resolution only works if that is the registry the worker
+     * dispatches on. Omit to have the worker create its own.
+     */
+    registry?: FunctionRegistry;
 }
 export declare class Worker {
     private _registry;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "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)",
@@ -87,12 +87,12 @@
   },
   "peerDependencies": {
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.15.1"
+    "@query-farm/vgi-rpc": "^0.15.4"
   },
   "devDependencies": {
     "@duckdb/node-api": "^1.5.2-r.1",
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.15.1",
+    "@query-farm/vgi-rpc": "^0.15.4",
     "@types/bun": "latest",
     "typescript": "^6.0.3"
   },

package/src/cache-control.ts

@@ -42,6 +42,7 @@ export const CACHE_STALE_WHILE_REVALIDATE_KEY = "vgi.cache.stale_while_revalidat
 export const CACHE_STALE_IF_ERROR_KEY = "vgi.cache.stale_if_error";
 export const CACHE_NOT_MODIFIED_KEY = "vgi.cache.not_modified";
 export const CACHE_PARTITION_SCOPE_KEY = "vgi.cache.partition_scope";
+export const CACHE_PER_VALUE_KEY = "vgi.cache.per_value";
 
 // --- Request-side metadata keys (client -> worker) --------------------------
 // Ride on the first producer tick; surfaced as `TableProcessParams.ifNoneMatch`
@@ -98,6 +99,31 @@ export interface CacheControl {
    *  partitions without calling the worker. Only meaningful for a
    *  `SINGLE_VALUE_PARTITIONS` table function; purely additive. */
   partitionScope?: boolean;
+  /**
+   * Opt in to per-VALUE memoization: in addition to the whole-result entry, the
+   * client memoizes each distinct worker-input tuple's output keyed on that
+   * tuple, so the same value is served without calling the worker on a later
+   * chunk or a later query. Only meaningful for an exchange-mode MAP — a
+   * scalar, or a blended table-in-out invoked through a correlated `LATERAL`.
+   *
+   * **Default off, and it should stay off unless one call is genuinely
+   * expensive.** This is not a free win: serving a value from the memo costs a
+   * key probe, a decode and a per-value assembly step, and that only pays back
+   * when it is cheaper than asking you for the answer. For a cheap map —
+   * arithmetic, a string tweak, a lookup in a table the worker already has in
+   * memory — it is a large net loss (the engine measures a per-value serve at
+   * roughly 50x the cost of just calling the worker for a simple arithmetic
+   * map). Only the function author knows which side of that line a call falls
+   * on, which is why the engine will not guess: turn it on for model
+   * inference, geocoding, an external API call, or anything rate-limited or
+   * billed per request.
+   *
+   * Independent of freshness: `ttl`/`expires` make a result cacheable at all,
+   * while this decides whether the per-value tier is additionally populated.
+   * Requires a deterministic, side-effect-free function, exactly like the rest
+   * of the result cache.
+   */
+  perValue?: boolean;
 }
 
 const VALID_SCOPES: readonly string[] = [CACHE_SCOPE_CATALOG, CACHE_SCOPE_TRANSACTION];
@@ -137,5 +163,6 @@ export function cacheControlMetadata(cc: CacheControl, extra?: Map<string, strin
   if (cc.staleIfError !== undefined) md.set(CACHE_STALE_IF_ERROR_KEY, String(cc.staleIfError));
   if (cc.notModified) md.set(CACHE_NOT_MODIFIED_KEY, "1");
   if (cc.partitionScope) md.set(CACHE_PARTITION_SCOPE_KEY, "1");
+  if (cc.perValue) md.set(CACHE_PER_VALUE_KEY, "1");
   return md;
 }

package/src/catalog/composite.ts

@@ -56,6 +56,15 @@ export class CompositeCatalogInterface extends CatalogInterface {
     return route;
   }
 
+  /** Route to the owning backend and ask it, so the answer is per-attachment. */
+  override catalogNameForAttach(attachOpaqueData: Uint8Array): string | null {
+    try {
+      return this._route(attachOpaqueData).catalogNameForAttach(attachOpaqueData);
+    } catch {
+      return null; // Unroutable attach — fall back to unscoped resolution.
+    }
+  }
+
   catalogs(): string[] {
     const all: string[] = [];
     for (const b of this._backends) all.push(...b.catalogs());

package/src/catalog/interface.ts

@@ -365,6 +365,21 @@ function isPromise<T>(v: Awaitable<T>): v is Promise<T> {
 }
 
 export abstract class CatalogInterface {
+  /**
+   * Which catalog an `attach_opaque_data` belongs to, or null if unknown.
+   *
+   * Two catalogs served by one worker may declare the same schema *and*
+   * function name, in which case the attachment is the only thing that tells
+   * them apart — the bind path uses this to scope function resolution. The
+   * default answers from `catalogs()` when this interface owns exactly one,
+   * which is right for every single-catalog implementation; the composite
+   * overrides it to route by its backend index byte.
+   */
+  catalogNameForAttach(_attachOpaqueData: Uint8Array): string | null {
+    const names = this.catalogs();
+    return names.length === 1 ? names[0] : null;
+  }
+
   // Required overrides
   abstract catalogs(): string[];
   /**

package/src/catalog/read-only.ts

@@ -38,6 +38,19 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
     super();
     this._descriptor = descriptor;
     this._registry = registry;
+    // Index every function this catalog declares by its owning schema, so a
+    // schema-qualified bind resolves to the right implementation when one name
+    // is declared in more than one schema. Table-backing functions are indexed
+    // under their table's schema for the same reason.
+    for (const sch of descriptor.schemas ?? []) {
+      for (const fn of sch.functions ?? []) registry.registerInSchema(fn, sch.name, descriptor.name);
+      for (const tbl of sch.tables ?? []) {
+        for (const key of ["function", "insertFunction", "updateFunction", "deleteFunction"] as const) {
+          const fn = (tbl as any)[key];
+          if (fn) registry.registerInSchema(fn, sch.name, descriptor.name);
+        }
+      }
+    }
   }
 
   catalogs(): string[] {

package/src/functions/registry.ts

@@ -16,6 +16,20 @@ export interface OverloadContext {
   arguments?: Arguments;
   inputSchema?: VgiSchema | null;
   isScalar?: boolean;
+  /**
+   * Catalog schema that declares the function, from `BindRequest.schema_name`.
+   * A worker may register the same name in more than one schema, so the bare
+   * name is not a unique key. When set, resolution is scoped to that schema and
+   * never falls back to another one; when absent, every schema is searched.
+   */
+  schemaName?: string | null;
+  /**
+   * Catalog that owns the function, resolved from the bind's
+   * `attach_opaque_data`. Two catalogs served by one worker may each declare
+   * the same schema *and* function name, in which case only the catalog tells
+   * them apart. Absent for calls with no attachment.
+   */
+  catalogName?: string | null;
 }
 
 const EXACT_MATCH_SCORE = 2;
@@ -190,8 +204,26 @@ function filterByArgumentTypes(
   return scored.filter(s => s.score === maxScore).map(s => s.func);
 }
 
+/** Key for the schema-scoped index: lowercased schema, then function name. */
+function schemaKey(schemaName: string, functionName: string): string {
+  return `${schemaName.toLowerCase()}\u0000${functionName}`;
+}
+
+/** Key for the catalog-scoped index: lowercased catalog, then the schema key. */
+function catalogKey(catalogName: string, schemaName: string, functionName: string): string {
+  return `${catalogName.toLowerCase()}\u0000${schemaKey(schemaName, functionName)}`;
+}
+
 export class FunctionRegistry {
   private _functions: Map<string, VgiFunction[]> = new Map();
+  // (lowercased schema, function name) -> functions declared in that schema.
+  // Populated by registerInSchema(), which catalog construction calls for every
+  // function a SchemaDescriptor lists. Lets a schema-qualified bind pick the
+  // right implementation when one name is registered in several schemas.
+  private _bySchema: Map<string, VgiFunction[]> = new Map();
+  // (lowercased catalog, lowercased schema, function name) -> functions. Needed
+  // because two catalogs in one worker may declare the same schema AND name.
+  private _byCatalog: Map<string, VgiFunction[]> = new Map();
 
   register(func: VgiFunction): void {
     const name = func.meta.name;
@@ -201,12 +233,85 @@ export class FunctionRegistry {
     this._functions.get(name)!.push(func);
   }
 
+  /**
+   * Record that `func` is declared in `schemaName`, in addition to the flat
+   * by-name index. Idempotent, and independent of `register()` so a function
+   * reachable from several schemas (e.g. a scan function referenced by tables in
+   * more than one schema) resolves from any of them.
+   */
+  registerInSchema(func: VgiFunction, schemaName: string, catalogName?: string): void {
+    const add = (map: Map<string, VgiFunction[]>, key: string) => {
+      const bucket = map.get(key);
+      if (!bucket) {
+        map.set(key, [func]);
+        return;
+      }
+      if (!bucket.includes(func)) bucket.push(func);
+    };
+    add(this._bySchema, schemaKey(schemaName, func.meta.name));
+    if (catalogName) {
+      add(this._byCatalog, catalogKey(catalogName, schemaName, func.meta.name));
+    }
+  }
+
+  /** Schemas that declare `functionName`, sorted — for error messages. */
+  schemasFor(functionName: string): string[] {
+    const out: string[] = [];
+    for (const key of this._bySchema.keys()) {
+      const [schema, name] = key.split("\u0000");
+      if (name === functionName) out.push(schema);
+    }
+    return out.sort();
+  }
+
   get(name: string, context?: OverloadContext): VgiFunction {
-    const candidates = this._functions.get(name);
+    let candidates = this._functions.get(name);
+
+    // A schema-qualified lookup is exact: only functions declared in that schema
+    // are candidates, so a name registered in two schemas dispatches to the one
+    // the caller named rather than colliding as an overload.
+    // Catalog first: it is the only key that separates two catalogs declaring
+    // the same schema and name.
+    const catalogName = context?.catalogName;
+    const schemaName = context?.schemaName;
+    if (catalogName && schemaName) {
+      const scoped = this._byCatalog.get(catalogKey(catalogName, schemaName, name));
+      if (scoped && scoped.length > 0) {
+        return this._disambiguate(name, scoped, context);
+      }
+    }
+    if (schemaName) {
+      const scoped = this._bySchema.get(schemaKey(schemaName, name));
+      if (scoped && scoped.length > 0) {
+        candidates = scoped;
+      } else if (candidates && candidates.length > 0) {
+        const schemas = this.schemasFor(name);
+        if (schemas.length > 0) {
+          throw new Error(
+            `Function '${name}' is not registered in schema '${schemaName}'. ` +
+              `It is available in: [${schemas.join(", ")}]`,
+          );
+        }
+      }
+    }
+
     if (!candidates || candidates.length === 0) {
       throw new FunctionNotFoundError(name, this.names());
     }
 
+    return this._disambiguate(name, candidates, context);
+  }
+
+  /**
+   * Pick one function from an already-scoped candidate list, by argument shape
+   * and types. Scoping (catalog / schema) happens in `get()`; by the time this
+   * runs, every candidate is a legitimate overload of the same name.
+   */
+  private _disambiguate(
+    name: string,
+    candidates: VgiFunction[],
+    context?: OverloadContext,
+  ): VgiFunction {
     // Fast path: single candidate
     if (candidates.length === 1) {
       return candidates[0];

package/src/functions/scalar.ts

@@ -185,10 +185,14 @@ export interface ScalarFunctionConfig<
   /**
    * Result-cache opt-in: when set, this CacheControl's `vgi.cache.*` metadata
    * rides every output batch's custom metadata (per-batch — NOT the schema,
-   * which the IPC stream fixes at open), so the extension can memoize the
-   * scalar's output per distinct input value. A pure, deterministic scalar
-   * only — advertising this on a non-pure scalar serves stale rows. Mirrors
+   * which the IPC stream fixes at open). A pure, deterministic scalar only —
+   * advertising this on a non-pure scalar serves stale rows. Mirrors
    * vgi-python's `ScalarFunction.CACHE_CONTROL`.
+   *
+   * Per-VALUE memoization (the extension remembering one output per distinct
+   * input value) additionally requires `perValue: true`, which is off by
+   * default because a memo serve only beats a worker call when the call is
+   * expensive — see {@link CacheControl.perValue}.
    */
   cacheControl?: CacheControl;
 }
@@ -405,8 +409,9 @@ export function defineScalarFunction<
           }
 
           // Result-cache opt-in: a scalar declaring cacheControl rides its
-          // vgi.cache.* keys on the emit path's per-batch custom metadata so
-          // the extension can memoize the output per distinct input value.
+          // vgi.cache.* keys on the emit path's per-batch custom metadata. The
+          // per-value memo tier is only populated when that CacheControl also
+          // sets `perValue` (default off — it costs more than a cheap call).
           out.emit(
             outputBatch,
             config.cacheControl ? cacheControlMetadata(config.cacheControl) : undefined,

package/src/generated/vgi-client.ts

@@ -2,7 +2,7 @@
 // GENERATED by vgi.codegen.ts_client. DO NOT EDIT BY HAND.
 //
 // Generator: vgi-gen-ts-client v1
-// Content hash: 226553bd666c
+// Content hash: 80ec56060e88
 //
 // To regenerate:
 //   uv run --project ~/Development/vgi-python vgi-gen-ts-client \
@@ -174,6 +174,7 @@ export interface AggregateBindRequest {
   settings?: /** @record-batch */ Uint8Array | null;
   secrets?: /** @record-batch */ Uint8Array | null;
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateBindResponse {
@@ -186,6 +187,7 @@ export interface AggregateCombineRequest {
   execution_id: Uint8Array;
   merge_batch: Uint8Array;
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateCombineResponse {
@@ -196,6 +198,7 @@ export interface AggregateDestructorRequest {
   execution_id: Uint8Array;
   group_ids_batch: Uint8Array;
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateDestructorResponse {
@@ -207,6 +210,7 @@ export interface AggregateFinalizeRequest {
   group_ids_batch: Uint8Array;
   output_schema: /** @arrow-schema */ Uint8Array;
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateFinalizeResponse {
@@ -218,6 +222,7 @@ export interface AggregateStreamingChunkRequest {
   execution_id: Uint8Array;
   input_batch: Uint8Array;
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateStreamingChunkResponse {
@@ -228,6 +233,7 @@ export interface AggregateStreamingCloseRequest {
   function_name: string;
   execution_id: Uint8Array;
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateStreamingCloseResponse {
@@ -243,6 +249,7 @@ export interface AggregateStreamingOpenRequest {
   settings?: /** @record-batch */ Uint8Array | null;
   secrets?: /** @record-batch */ Uint8Array | null;
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateStreamingOpenResponse {
@@ -254,6 +261,7 @@ export interface AggregateUpdateRequest {
   execution_id: Uint8Array;
   input_batch: Uint8Array;
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateUpdateResponse {
@@ -267,6 +275,7 @@ export interface AggregateWindowRequest {
   frame_starts: number[];
   frame_ends: number[];
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateWindowResponse {
@@ -283,6 +292,7 @@ export interface AggregateWindowBatchRequest {
   frame_starts: number[];
   frame_ends: number[];
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateWindowBatchResponse {
@@ -294,6 +304,7 @@ export interface AggregateWindowDestructorRequest {
   execution_id: Uint8Array;
   partition_id: number;
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateWindowDestructorResponse {
@@ -310,6 +321,7 @@ export interface AggregateWindowInitRequest {
   frame_stats: Uint8Array;
   all_valid: Uint8Array;
   attach_opaque_data?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface AggregateWindowInitResponse {
@@ -340,6 +352,7 @@ export interface BindRequest {
   at_value?: string | null;
   copy_from?: CopyFromContext | null;
   copy_to?: CopyToContext | null;
+  schema_name?: string | null;
 }
 
 export interface BindResponse {
@@ -487,6 +500,7 @@ export interface TableBufferingCombineRequest {
   state_ids: Uint8Array[];
   attach_opaque_data?: Uint8Array | null;
   transaction_id?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface TableBufferingCombineResponse {
@@ -498,6 +512,7 @@ export interface TableBufferingDestructorRequest {
   execution_id: Uint8Array;
   attach_opaque_data?: Uint8Array | null;
   transaction_id?: Uint8Array | null;
+  schema_name?: string | null;
 }
 
 export interface TableBufferingDestructorResponse {
@@ -510,6 +525,7 @@ export interface TableBufferingProcessRequest {
   attach_opaque_data?: Uint8Array | null;
   transaction_id?: Uint8Array | null;
   batch_index?: number | null;
+  schema_name?: string | null;
 }
 
 export interface TableBufferingProcessResponse {

package/src/index.core.ts

@@ -17,6 +17,7 @@ export {
   CACHE_NO_STORE_KEY,
   CACHE_NOT_MODIFIED_KEY,
   CACHE_PARTITION_SCOPE_KEY,
+  CACHE_PER_VALUE_KEY,
   CACHE_REVALIDATABLE_KEY,
   CACHE_SCOPE_CATALOG,
   CACHE_SCOPE_KEY,

package/src/protocol/dispatch.ts

@@ -43,6 +43,7 @@ export function buildVgiProtocol(config: ProtocolConfig): Protocol {
     registry: config.registry,
     recoverExchangeState: config.recoverExchangeState,
     signingKey: config.signingKey,
+    catalogInterface: config.catalogInterface,
   });
   registerAggregateMethods(protocol, config.registry);
   registerTableBufferingMethods(protocol, config.registry, config.signingKey);

package/src/protocol/handlers/function.ts

@@ -35,10 +35,16 @@ export interface FunctionHandlerConfig {
   registry: FunctionRegistry;
   recoverExchangeState?: (opaqueData: Uint8Array) => any;
   signingKey?: Uint8Array;
+  /**
+   * Used to map a bind's `attach_opaque_data` to its catalog, so resolution can
+   * be scoped when two catalogs declare the same schema and function name.
+   * Optional — without it, resolution falls back to (schema, name).
+   */
+  catalogInterface?: { catalogNameForAttach(a: Uint8Array): string | null };
 }
 
 export function registerFunctionMethods(protocol: Protocol, config: FunctionHandlerConfig): void {
-  const { registry, signingKey } = config;
+  const { registry, signingKey, catalogInterface } = config;
 
   // The framework mints every attach as uuid(16) || catalog_bytes (sealed on
   // HTTP, plaintext on subprocess). Function bodies — like catalog bodies —
@@ -51,6 +57,21 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
     return openAttach(env, ctx?.auth, signingKey);
   }
 
+  // Build an overload context whose attach has been unsealed, so catalog
+  // resolution sees the real route byte. The bind/init handlers strip their
+  // request in place and can call overloadContext directly; every other site
+  // still holds the sealed envelope (73 bytes on HTTP vs 16 plaintext), whose
+  // leading byte would otherwise route to an arbitrary catalog.
+  async function strippedContext(bindCall: any, ctx?: any) {
+    let attach: Uint8Array | null = null;
+    try {
+      attach = await stripAttach(bindCall.attach_opaque_data, ctx);
+    } catch {
+      attach = null; // Unopenable (wrong key / not sealed) — resolve unscoped.
+    }
+    return overloadContext({ ...bindCall, attach_opaque_data: attach }, catalogInterface);
+  }
+
   const initHeaderSchema = schema([
     field("execution_id", binary(), false),
     field("opaque_data", binary(), true),
@@ -77,7 +98,7 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
       const innerParams = unwrapRequest(params.request);
       const request = deserializeBindRequest(innerParams);
       request.attach_opaque_data = await stripAttach(request.attach_opaque_data, ctx);
-      const func = registry.get(request.function_name, overloadContext(request));
+      const func = registry.get(request.function_name, overloadContext(request, catalogInterface));
       const response = await func.bind(request);
       const serialized = serializeBindResponse(response);
       return wrapResult(serialized, BindResultSchema);
@@ -99,7 +120,7 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
       // Exchange init has no ctx; on subprocess (no signing key) openAttach is a
       // pass-through strip that needs no auth. HTTP carries auth via the bind path.
       request.bind_call.attach_opaque_data = await stripAttach(request.bind_call.attach_opaque_data, undefined);
-      const func = registry.get(request.bind_call.function_name, overloadContext(request.bind_call));
+      const func = registry.get(request.bind_call.function_name, overloadContext(request.bind_call, catalogInterface));
 
       // globalInit is async — table function onInit may touch HTTP-backed
       // FunctionStorage (e.g. Cloudflare DO).
@@ -178,7 +199,7 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
         const initRequestBatch = deserializeBatch(state.initRequestIpc);
         const initRequestDict = batchToScalarDict(initRequestBatch);
         const request = deserializeInitRequest(initRequestDict);
-        const func = registry.get(state.functionName, overloadContext(request.bind_call));
+        const func = registry.get(state.functionName, await strippedContext(request.bind_call));
         const executionId = state.executionId;
         const opaqueData = state.opaqueData ?? null;
         const initResponse: GlobalInitResponse = {
@@ -243,7 +264,7 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
     handler: async (params) => {
       const innerParams = unwrapRequest(params.request);
       const request = deserializeCardinalityRequest(innerParams);
-      const func = registry.get(request.bind_call.function_name, overloadContext(request.bind_call));
+      const func = registry.get(request.bind_call.function_name, await strippedContext(request.bind_call));
       let cardResult: Record<string, any>;
       if (func.cardinality) {
         cardResult = serializeTableCardinality(await func.cardinality(request));
@@ -264,10 +285,10 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
   protocol.unary("table_function_statistics", {
     params: REQUEST_PARAMS_SCHEMA,
     result: RESULT_BINARY_NULLABLE_SCHEMA,
-    handler: (params) => {
+    handler: async (params) => {
       const innerParams = unwrapRequest(params.request);
       const request = deserializeCardinalityRequest(innerParams);
-      const func = registry.get(request.bind_call.function_name, overloadContext(request.bind_call));
+      const func = registry.get(request.bind_call.function_name, await strippedContext(request.bind_call));
       if (!func.statistics) return { result: null };
       const stats = func.statistics(request);
       if (!stats || stats.length === 0) return { result: null };
@@ -298,7 +319,7 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
       const bindOpaqueData = innerParams.bind_opaque_data
         ? toUint8Array(innerParams.bind_opaque_data)
         : null;
-      const func = registry.get(bindCall.function_name, overloadContext(bindCall));
+      const func = registry.get(bindCall.function_name, await strippedContext(bindCall));
       const map = func.dynamicToString
         ? await func.dynamicToString({ bindCall, bindOpaqueData, globalExecutionId })
         : {};

package/src/protocol/handlers/shared.ts

@@ -51,11 +51,35 @@ export function wrapResult(
   return { result: serializeBatch(batch) };
 }
 
-export function overloadContext(req: { function_name: string; arguments: any; input_schema: any; function_type: any }): OverloadContext {
+export function overloadContext(
+  req: {
+    function_name: string;
+    arguments: any;
+    input_schema: any;
+    function_type: any;
+    schema_name?: string | null;
+    attach_opaque_data?: Uint8Array | null;
+  },
+  catalogInterface?: { catalogNameForAttach(a: Uint8Array): string | null },
+): OverloadContext {
+  // The attachment identifies the catalog, which is the only key separating two
+  // catalogs that declare the same schema AND function name.
+  let catalogName: string | null = null;
+  if (catalogInterface && req.attach_opaque_data) {
+    try {
+      catalogName = catalogInterface.catalogNameForAttach(req.attach_opaque_data);
+    } catch {
+      catalogName = null;
+    }
+  }
   return {
     arguments: req.arguments,
     inputSchema: req.input_schema,
     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,
+    catalogName,
   };
 }
 

package/src/protocol/serializers/bind.ts

@@ -30,6 +30,10 @@ const BIND_REQUEST_SCHEMA = schema([
   // Both null when the scan has no AT clause. See BindRequest.at_unit.
   field("at_unit", utf8(), true),
   field("at_value", utf8(), 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),
 ]);
 
 // COPY ... FROM context — a nullable nested struct<format, file_path,
@@ -76,6 +80,7 @@ export function serializeBindRequest(req: BindRequest): VgiBatch {
     resolved_secrets_provided: req.resolved_secrets_provided ?? false,
     at_unit: req.at_unit ?? null,
     at_value: req.at_value ?? null,
+    schema_name: req.schema_name ?? null,
   };
   // Append the copy_from / copy_to struct columns only for COPY scans/sinks, so
   // non-COPY binds serialize to the exact legacy shape (fields matched by name
@@ -172,6 +177,8 @@ export function deserializeBindRequest(
     // Empty string -> null (matches the C++ BuildBindRequest convention).
     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,
     // 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/types.ts

@@ -88,6 +88,14 @@ export interface BindRequest {
    */
   at_unit?: string | null;
   at_value?: string | null;
+  /**
+   * 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,
+   * function_name)`. Null for callers with no catalog context (COPY handler
+   * binds). Mirrors vgi-python's `BindRequest.schema_name`.
+   */
+  schema_name?: string | null;
 }
 
 export interface BindResponse {