@query-farm/vgi 0.20.0 → 0.22.0

package/src/protocol/handlers/function.ts

@@ -16,7 +16,7 @@ import {
   serializeTableCardinality,
 } from "../serialize.js";
 import type { GlobalInitResponse } from "../types.js";
-import { batchToScalarDict, deserializeBatch } from "../../util/arrow/index.js";
+import { batchToScalarDict, deserializeBatch, adoptArrowJsShape } from "../../util/arrow/index.js";
 import { toUint8Array } from "../../util/bytes.js";
 import { serializeColumnStatistics } from "../../util/statistics.js";
 import { BindResultSchema, TableFunctionCardinalityResultSchema, TableFunctionDynamicToStringResultSchema } from "../../generated/vgi-protocol-schemas.js";
@@ -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).
@@ -153,6 +174,14 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
       return state;
     },
     exchange: async (state, input, out) => {
+      // `input` is the one batch worker code sees that this package did not
+      // decode — vgi-rpc read it off the wire with its own Arrow backend. If
+      // that resolved to a second copy of @query-farm/flechette (nested under
+      // vgi-rpc whenever the version ranges disagree, even transiently), the
+      // facade's prototype patches never touched its classes and user code
+      // gets `col.isValid is not a function` on the first exchange round.
+      // Adopting here is a WeakSet probe per call and a no-op on arrow-js.
+      input = adoptArrowJsShape(input);
       // Reconstruct live objects from serializable state.
       // This handles both immediate use (producer during init, where _handlers
       // is still present) and deserialized exchange (where we reconstruct).
@@ -170,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 = {
@@ -235,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));
@@ -256,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 };
@@ -290,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 {

package/src/util/arrow/index.ts

@@ -20,4 +20,5 @@ export {
   deserializeSchema,
   serializeBatch,
   deserializeBatch,
+  adoptArrowJsShape,
 } from "../../arrow/index.js";

package/src/worker.ts

@@ -65,6 +65,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 class Worker {
@@ -73,7 +81,10 @@ export class Worker {
   private _catalogName?: string;
 
   constructor(config: WorkerConfig) {
-    this._registry = new FunctionRegistry();
+    // Reuse the caller's registry when given: a catalogInterface built
+    // elsewhere recorded its per-schema function ownership there, and that
+    // index is what makes a schema-qualified bind resolve correctly.
+    this._registry = config.registry ?? new FunctionRegistry();
     this._catalogName = config.catalogName;
 
     // Register explicit functions
@@ -89,6 +100,9 @@ export class Worker {
         if (schema.functions) {
           for (const func of schema.functions) {
             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);
           }
         }
       }