@query-farm/vgi 0.41.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.41.0",
+  "version": "0.42.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)",

package/src/protocol/dispatch.ts

@@ -15,6 +15,7 @@ import { registerFunctionMethods } from "./handlers/function.js";
 import { registerAggregateMethods } from "./handlers/aggregate.js";
 import { registerTableBufferingMethods } from "./handlers/table-buffering.js";
 import { registerCatalogMethods } from "./handlers/catalog/index.js";
+import { registerUnimplementedMethods } from "./handlers/unimplemented.js";
 
 export interface ProtocolConfig {
   registry: FunctionRegistry;
@@ -56,6 +57,20 @@ export interface ProtocolConfig {
  */
 export const VGI_PROTOCOL_NAME = "vgi.v2";
 
+/**
+ * The `vgi.v2` protocol hash `vgi_rpc.Reflection.v1` must report for this
+ * worker: the reference's (vgi-python 0.43.0, 72 methods). Every SDK hosts
+ * every `vgi.v2` method with the reference's schemas, so the hash is one value
+ * across the ports; a method this SDK does not implement is still registered
+ * (handlers/unimplemented.ts). The hash covers method names, types and the
+ * params/result/header schemas only (WIRE_PROTOCOL.md §14).
+ *
+ * It changes only with vgi.v2's protocol version (currently 2.1.0). Asserted
+ * by src/protocol/__tests__/vgi-v2-hash.test.ts; if that test fails, the
+ * surface drifted from the reference -- fix the schemas, do not bump this.
+ */
+export const VGI_V2_PROTOCOL_HASH = "774cb80090d71ea76d09aa311b9cda4ca4c33c3bf72c43242eb6dc87b6f79ce5";
+
 export function buildVgiProtocol(config: ProtocolConfig): Protocol {
   const protocol = new Protocol(VGI_PROTOCOL_NAME, { protocolVersion: "2.1.0" });
 
@@ -67,6 +82,7 @@ export function buildVgiProtocol(config: ProtocolConfig): Protocol {
   registerAggregateMethods(protocol, config.registry);
   registerTableBufferingMethods(protocol, config.registry, config.signingKey);
   registerCatalogMethods(protocol, config.catalogInterface, config.catalogName, config.signingKey);
+  registerUnimplementedMethods(protocol);
 
   return protocol;
 }

package/src/protocol/handlers/unimplemented.ts

@@ -0,0 +1,74 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// vgi.v2 methods this SDK registers but does not implement.
+//
+// "The protocol is the unit of optionality": every SDK hosts EVERY vgi.v2
+// method with exactly the reference's schemas, so vgi_rpc.Reflection.v1
+// reports one vgi.v2 protocol hash everywhere (see VGI_V2_PROTOCOL_HASH in
+// ../dispatch.ts). A method this port has no implementation for is still
+// registered -- with the reference's params/result schemas -- and answers
+// every call with vgi-rpc's MethodNotImplementedError: error_code
+// UNIMPLEMENTED, error_kind method_not_implemented. Never a silent success.
+//
+// When one of these gains a real implementation, move it out of this list
+// into its handler module; the schemas must not change (the hash test fails
+// if they do).
+
+import { MethodNotImplementedError, type Protocol } from "@query-farm/vgi-rpc";
+import type { VgiSchema } from "../../arrow/index.js";
+import {
+  CatalogIndexCreateParamsSchema,
+  CatalogIndexDropParamsSchema,
+  CatalogTableColumnCommentSetParamsSchema,
+  CatalogTableDeleteFunctionGetParamsSchema,
+  CatalogTableInsertFunctionGetParamsSchema,
+  CatalogTableUpdateFunctionGetParamsSchema,
+} from "../../generated/vgi-protocol-schemas.js";
+import { REQUEST_PARAMS_SCHEMA, RESULT_BINARY_SCHEMA } from "./shared.js";
+import { emptyResultSchema } from "./catalog/shared.js";
+
+/** One unimplemented method: its wire name and the reference's schemas. */
+interface UnimplementedMethod {
+  readonly name: string;
+  readonly params: VgiSchema;
+  readonly result: VgiSchema;
+}
+
+/**
+ * The vgi.v2 methods (of the reference's 72) this SDK does not implement.
+ * Exported so a test can assert each one refuses with UNIMPLEMENTED.
+ */
+export const UNIMPLEMENTED_METHODS: readonly UnimplementedMethod[] = [
+  // Streaming and window aggregates: request/result are wrapped ASD blobs.
+  { name: "aggregate_streaming_open", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_streaming_chunk", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_streaming_close", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_window_init", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_window", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_window_batch", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  { name: "aggregate_window_destructor", params: REQUEST_PARAMS_SCHEMA, result: RESULT_BINARY_SCHEMA },
+  // Index DDL and per-column comments.
+  { name: "catalog_index_create", params: CatalogIndexCreateParamsSchema, result: emptyResultSchema },
+  { name: "catalog_index_drop", params: CatalogIndexDropParamsSchema, result: emptyResultSchema },
+  { name: "catalog_table_column_comment_set", params: CatalogTableColumnCommentSetParamsSchema, result: emptyResultSchema },
+  // Per-table DML function getters.
+  { name: "catalog_table_insert_function_get", params: CatalogTableInsertFunctionGetParamsSchema, result: RESULT_BINARY_SCHEMA },
+  { name: "catalog_table_update_function_get", params: CatalogTableUpdateFunctionGetParamsSchema, result: RESULT_BINARY_SCHEMA },
+  { name: "catalog_table_delete_function_get", params: CatalogTableDeleteFunctionGetParamsSchema, result: RESULT_BINARY_SCHEMA },
+];
+
+/** The message every unimplemented method answers with. */
+export function unimplementedMessage(method: string): string {
+  return `${method} is not implemented by this worker`;
+}
+
+export function registerUnimplementedMethods(protocol: Protocol): void {
+  for (const m of UNIMPLEMENTED_METHODS) {
+    protocol.unary(m.name, {
+      params: m.params,
+      result: m.result,
+      handler: async () => {
+        throw new MethodNotImplementedError(unimplementedMessage(m.name));
+      },
+    });
+  }
+}