@query-farm/vgi 0.41.0 → 0.43.0

package/src/protocol/handlers/catalog/index.ts

@@ -1,25 +1,26 @@
 // Copyright 2025, 2026 Query Farm LLC - https://query.farm
-// Catalog handler orchestrator: registers all catalog_* RPC methods.
+// Catalog handler orchestrator: every catalog_* `vgi.v2` handler.
 
-import { Protocol } from "@query-farm/vgi-rpc";
 import type { CatalogInterface } from "../../../catalog/interface.js";
+import type { VgiService } from "../../../generated/vgi-service.js";
 import { makeGetCatalog } from "./shared.js";
-import { registerCatalogAdminMethods } from "./admin.js";
-import { registerCatalogTableMethods } from "./table.js";
-import { registerCatalogViewMethods } from "./view.js";
-import { registerCatalogMacroMethods } from "./macro.js";
-import { registerCatalogIndexMethods } from "./index_methods.js";
+import { catalogAdminHandlers } from "./admin.js";
+import { catalogTableHandlers } from "./table.js";
+import { catalogViewHandlers } from "./view.js";
+import { catalogMacroHandlers } from "./macro.js";
+import { catalogIndexHandlers } from "./index_methods.js";
 
-export function registerCatalogMethods(
-  protocol: Protocol,
+/** The catalog_* `vgi.v2` handlers, over *catalog* (or `NoCatalogError` without one). */
+export function catalogHandlers(
   catalog: CatalogInterface | undefined,
-  _catalogName: string | undefined,
   signingKey?: Uint8Array,
-): void {
+): Partial<VgiService> {
   const getCatalog = makeGetCatalog(catalog);
-  registerCatalogAdminMethods(protocol, getCatalog, signingKey);
-  registerCatalogTableMethods(protocol, getCatalog, signingKey);
-  registerCatalogViewMethods(protocol, getCatalog, signingKey);
-  registerCatalogMacroMethods(protocol, getCatalog, signingKey);
-  registerCatalogIndexMethods(protocol, getCatalog, signingKey);
+  return {
+    ...catalogAdminHandlers(getCatalog, signingKey),
+    ...catalogTableHandlers(getCatalog, signingKey),
+    ...catalogViewHandlers(getCatalog, signingKey),
+    ...catalogMacroHandlers(getCatalog, signingKey),
+    ...catalogIndexHandlers(getCatalog, signingKey),
+  };
 }

package/src/protocol/handlers/catalog/index_methods.ts

@@ -1,58 +1,48 @@
 // Copyright 2025, 2026 Query Farm LLC - https://query.farm
 // Catalog index handlers: index_get, schema_contents_indexes.
 
-import { type VgiSchema, schema, type VgiField, field, type VgiDataType, binary, utf8 } from "../../../arrow/index.js";
-import { Protocol } from "@query-farm/vgi-rpc";
+import type { VgiService } from "../../../generated/vgi-service.js";
 import { encodeIndexInfo } from "../../../generated/vgi-client.js";
 import {
-  CatalogIndexGetParamsSchema,
   CatalogIndexGetResultSchema,
-  CatalogSchemaContentsIndexesParamsSchema,
   CatalogSchemaContentsIndexesResultSchema,
 } from "../../../generated/vgi-protocol-schemas.js";
 import { toUint8Array } from "../../../util/bytes.js";
 import {
-  RESULT_BINARY_SCHEMA,
   wrapResult,
 } from "../shared.js";
 import {
   type GetCatalog,
-  catalogUnary,
+  catalogHandler,
 } from "./shared.js";
 
-export function registerCatalogIndexMethods(protocol: Protocol, getCatalog: GetCatalog, signingKey?: Uint8Array): void {
+export function catalogIndexHandlers(getCatalog: GetCatalog, signingKey?: Uint8Array): Partial<VgiService> {
   // catalog_schema_contents_indexes
-  catalogUnary(protocol, signingKey, "catalog_schema_contents_indexes", {
-    params: CatalogSchemaContentsIndexesParamsSchema,
-    result: RESULT_BINARY_SCHEMA,
-    handler: async (params) => {
-      const cat = getCatalog();
-      const indexes = await cat.schemaContentsIndexes(
-        toUint8Array(params.attach_opaque_data),
-        params.path,
-        params.transaction_opaque_data ? toUint8Array(params.transaction_opaque_data) : undefined,
-      );
-      return wrapResult({
-        items: indexes.map((i) => encodeIndexInfo(i)),
-      }, CatalogSchemaContentsIndexesResultSchema);
-    },
+  const catalogSchemaContentsIndexes = catalogHandler(signingKey, async (params) => {
+    const cat = getCatalog();
+    const indexes = await cat.schemaContentsIndexes(
+      toUint8Array(params.attach_opaque_data),
+      params.path,
+      params.transaction_opaque_data ? toUint8Array(params.transaction_opaque_data) : undefined,
+    );
+    return wrapResult({
+      items: indexes.map((i) => encodeIndexInfo(i)),
+    }, CatalogSchemaContentsIndexesResultSchema);
   });
 
   // catalog_index_get
-  catalogUnary(protocol, signingKey, "catalog_index_get", {
-    params: CatalogIndexGetParamsSchema,
-    result: RESULT_BINARY_SCHEMA,
-    handler: async (params) => {
-      const cat = getCatalog();
-      const info = await cat.indexGet(
-        toUint8Array(params.attach_opaque_data),
-        params.schema_path,
-        params.name,
-        params.transaction_opaque_data ? toUint8Array(params.transaction_opaque_data) : undefined,
-      );
-      return wrapResult({
-        items: info ? [encodeIndexInfo(info)] : [],
-      }, CatalogIndexGetResultSchema);
-    },
+  const catalogIndexGet = catalogHandler(signingKey, async (params) => {
+    const cat = getCatalog();
+    const info = await cat.indexGet(
+      toUint8Array(params.attach_opaque_data),
+      params.schema_path,
+      params.name,
+      params.transaction_opaque_data ? toUint8Array(params.transaction_opaque_data) : undefined,
+    );
+    return wrapResult({
+      items: info ? [encodeIndexInfo(info)] : [],
+    }, CatalogIndexGetResultSchema);
   });
+
+  return { catalogSchemaContentsIndexes, catalogIndexGet };
 }

package/src/protocol/handlers/catalog/macro.ts

@@ -1,107 +1,84 @@
 // Copyright 2025, 2026 Query Farm LLC - https://query.farm
 // Catalog macro handlers: macro_get/create/drop, schema_contents_macros.
 
-import { type VgiSchema, schema, type VgiField, field, type VgiDataType, binary, utf8, bool } from "../../../arrow/index.js";
-import { Protocol } from "@query-farm/vgi-rpc";
+import type { VgiService } from "../../../generated/vgi-service.js";
 import { encodeMacroInfo } from "../../../generated/vgi-client.js";
 import {
-  CatalogMacroCreateParamsSchema,
-  CatalogMacroDropParamsSchema,
-  CatalogMacroGetParamsSchema,
   CatalogMacroGetResultSchema,
-  CatalogSchemaContentsMacrosParamsSchema,
   CatalogSchemaContentsMacrosResultSchema,
 } from "../../../generated/vgi-protocol-schemas.js";
 import type { MacroType } from "../../../catalog/interface.js";
 import { toUint8Array } from "../../../util/bytes.js";
 import { decodeDictValue } from "../../../util/arrow/index.js";
 import {
-  REQUEST_PARAMS_SCHEMA,
-  RESULT_BINARY_SCHEMA,
-  unwrapRequest,
   wrapResult,
 } from "../shared.js";
 import {
   type GetCatalog,
-  emptyResultSchema,
-  catalogUnary,
+  catalogHandler,
 } from "./shared.js";
 
-export function registerCatalogMacroMethods(protocol: Protocol, getCatalog: GetCatalog, signingKey?: Uint8Array): void {
+export function catalogMacroHandlers(getCatalog: GetCatalog, signingKey?: Uint8Array): Partial<VgiService> {
   // catalog_macro_get
-  catalogUnary(protocol, signingKey, "catalog_macro_get", {
-    params: CatalogMacroGetParamsSchema,
-    result: RESULT_BINARY_SCHEMA,
-    handler: async (params) => {
-      const cat = getCatalog();
-      const info = await cat.macroGet(
-        toUint8Array(params.attach_opaque_data),
-        params.schema_path,
-        params.name,
-        params.transaction_opaque_data ? toUint8Array(params.transaction_opaque_data) : undefined
-      );
-      return wrapResult({
-        items: info ? [encodeMacroInfo(info)] : [],
-      }, CatalogMacroGetResultSchema);
-    },
+  const catalogMacroGet = catalogHandler(signingKey, async (params) => {
+    const cat = getCatalog();
+    const info = await cat.macroGet(
+      toUint8Array(params.attach_opaque_data),
+      params.schema_path,
+      params.name,
+      params.transaction_opaque_data ? toUint8Array(params.transaction_opaque_data) : undefined
+    );
+    return wrapResult({
+      items: info ? [encodeMacroInfo(info)] : [],
+    }, CatalogMacroGetResultSchema);
   });
 
   // catalog_macro_create
-  catalogUnary(protocol, signingKey, "catalog_macro_create", {
-    params: CatalogMacroCreateParamsSchema,
-    result: emptyResultSchema,
-    handler: async (params) => {
-      const cat = getCatalog();
-      // catalogUnary already flattened the wrapped request.
-      const innerParams = params;
-      await cat.macroCreate(
-        toUint8Array(innerParams.attach_opaque_data),
-        innerParams.schema_path,
-        innerParams.name,
-        innerParams.macro_type as MacroType,
-        innerParams.parameters ? (Array.isArray(innerParams.parameters) ? innerParams.parameters : [...innerParams.parameters]) : [],
-        innerParams.definition,
-        innerParams.on_conflict,
-        innerParams.parameter_default_values ? toUint8Array(innerParams.parameter_default_values) : null,
-        innerParams.arguments_schema ? toUint8Array(innerParams.arguments_schema) : null,
-        innerParams.transaction_opaque_data ? toUint8Array(innerParams.transaction_opaque_data) : undefined
-      );
-      return {};
-    },
+  const catalogMacroCreate = catalogHandler(signingKey, async (params) => {
+    const cat = getCatalog();
+    // catalogHandler already flattened the wrapped request.
+    const innerParams = params;
+    await cat.macroCreate(
+      toUint8Array(innerParams.attach_opaque_data),
+      innerParams.schema_path,
+      innerParams.name,
+      innerParams.macro_type as MacroType,
+      innerParams.parameters ? (Array.isArray(innerParams.parameters) ? innerParams.parameters : [...innerParams.parameters]) : [],
+      innerParams.definition,
+      innerParams.on_conflict,
+      innerParams.parameter_default_values ? toUint8Array(innerParams.parameter_default_values) : null,
+      innerParams.arguments_schema ? toUint8Array(innerParams.arguments_schema) : null,
+      innerParams.transaction_opaque_data ? toUint8Array(innerParams.transaction_opaque_data) : undefined
+    );
+    return {};
   });
 
   // catalog_macro_drop
-  catalogUnary(protocol, signingKey, "catalog_macro_drop", {
-    params: CatalogMacroDropParamsSchema,
-    result: emptyResultSchema,
-    handler: async (params) => {
-      const cat = getCatalog();
-      await cat.macroDrop(
-        toUint8Array(params.attach_opaque_data),
-        params.schema_path,
-        params.name,
-        params.ignore_not_found,
-        params.transaction_opaque_data ? toUint8Array(params.transaction_opaque_data) : undefined
-      );
-      return {};
-    },
+  const catalogMacroDrop = catalogHandler(signingKey, async (params) => {
+    const cat = getCatalog();
+    await cat.macroDrop(
+      toUint8Array(params.attach_opaque_data),
+      params.schema_path,
+      params.name,
+      params.ignore_not_found,
+      params.transaction_opaque_data ? toUint8Array(params.transaction_opaque_data) : undefined
+    );
+    return {};
   });
 
   // catalog_schema_contents_macros
-  catalogUnary(protocol, signingKey, "catalog_schema_contents_macros", {
-    params: CatalogSchemaContentsMacrosParamsSchema,
-    result: RESULT_BINARY_SCHEMA,
-    handler: async (params) => {
-      const cat = getCatalog();
-      const macros = await cat.schemaContentsMacros(
-        toUint8Array(params.attach_opaque_data),
-        params.path,
-        decodeDictValue(params.type),
-        params.transaction_opaque_data ? toUint8Array(params.transaction_opaque_data) : undefined
-      );
-      return wrapResult({
-        items: macros.map((m) => encodeMacroInfo(m)),
-      }, CatalogSchemaContentsMacrosResultSchema);
-    },
+  const catalogSchemaContentsMacros = catalogHandler(signingKey, async (params) => {
+    const cat = getCatalog();
+    const macros = await cat.schemaContentsMacros(
+      toUint8Array(params.attach_opaque_data),
+      params.path,
+      decodeDictValue(params.type),
+      params.transaction_opaque_data ? toUint8Array(params.transaction_opaque_data) : undefined
+    );
+    return wrapResult({
+      items: macros.map((m) => encodeMacroInfo(m)),
+    }, CatalogSchemaContentsMacrosResultSchema);
   });
+
+  return { catalogMacroGet, catalogMacroCreate, catalogMacroDrop, catalogSchemaContentsMacros };
 }

package/src/protocol/handlers/catalog/shared.ts

@@ -1,8 +1,8 @@
 // Copyright 2025, 2026 Query Farm LLC - https://query.farm
 // Shared param schemas and helpers for catalog protocol handlers.
 
-import { type VgiSchema, schema, iterRows } from "../../../arrow/index.js";
-import { Protocol, type AuthContext, type CallContext } from "@query-farm/vgi-rpc";
+import { iterRows } from "../../../arrow/index.js";
+import type { AuthContext, CallContext } from "@query-farm/vgi-rpc";
 import type { CatalogInterface } from "../../../catalog/interface.js";
 import { NoCatalogError } from "../../../errors.js";
 import { deserializeBatch } from "../../../util/arrow/index.js";
@@ -174,43 +174,32 @@ async function unwrapParamsOpaque(
 }
 
 /**
- * Register a catalog unary handler whose request opaque-data fields are
- * unwrapped before the handler body runs. Used for every catalog_* method
- * except catalog_attach / catalog_transaction_begin, which seal their outputs
- * and are registered bespoke.
+ * Wrap a catalog unary handler so its request opaque-data fields are unwrapped
+ * before the body runs. Used for every catalog_* method except catalog_attach
+ * / catalog_transaction_begin, which seal their outputs and are written
+ * bespoke. The body sees the flattened params as a plain record.
  */
-export function catalogUnary(
-  protocol: Protocol,
+export function catalogHandler<R>(
   signingKey: Uint8Array | undefined,
-  name: string,
-  config: {
-    params: unknown;
-    result: unknown;
-    handler: (params: Record<string, any>, ctx: CallContext) => unknown;
-    doc?: string;
-  },
-): void {
-  protocol.unary(name, {
-    params: config.params as any,
-    result: config.result as any,
-    doc: config.doc,
-    handler: async (params: Record<string, any>, ctx: any) => {
-      // catalog_create / catalog_table_create / catalog_macro_create (and
-      // catalog_index_create) send one `request: binary` column holding the
-      // IPC-serialized request record, so their attach/transaction values ride
-      // INSIDE it. Flatten it first, so handlers read the request's fields
-      // directly and those values are opened (and the framework UUID stripped)
-      // like every other catalog call's. Before this, table_create read every
-      // field off the envelope (all undefined) and macro_create handed the
-      // catalog an unopened attach value.
-      if (params.request != null && params.attach_opaque_data === undefined && params.name === undefined) {
-        params = unwrapRequest(params.request);
-      }
-      normalizeRequestSchemaPaths(params);
-      await unwrapParamsOpaque(params, ctx, signingKey);
-      return config.handler(params, ctx);
-    },
-  });
+  handler: (params: Record<string, any>, ctx: CallContext) => R | Promise<R>,
+): (params: object, ctx: CallContext) => Promise<R> {
+  return async (wire: object, ctx: CallContext) => {
+    let params = wire as Record<string, any>;
+    // catalog_create / catalog_table_create / catalog_macro_create (and
+    // catalog_index_create) send one `request: binary` column holding the
+    // IPC-serialized request record, so their attach/transaction values ride
+    // INSIDE it. Flatten it first, so handlers read the request's fields
+    // directly and those values are opened (and the framework UUID stripped)
+    // like every other catalog call's. Before this, table_create read every
+    // field off the envelope (all undefined) and macro_create handed the
+    // catalog an unopened attach value.
+    if (params.request != null && params.attach_opaque_data === undefined && params.name === undefined) {
+      params = unwrapRequest(params.request);
+    }
+    normalizeRequestSchemaPaths(params);
+    await unwrapParamsOpaque(params, ctx, signingKey);
+    return handler(params, ctx);
+  };
 }
 
 export function makeGetCatalog(catalog: CatalogInterface | undefined): GetCatalog {
@@ -240,18 +229,12 @@ export function decodeOptionsBatch(bytes: any): Record<string, unknown> {
   return row ?? {};
 }
 
-// ---------------------------------------------------------------------------
-// Common param schemas
-// ---------------------------------------------------------------------------
-
-export const emptyResultSchema = schema([]);
-
 // Eight hand-written catalog param schemas used to live here, restating shapes
-// codegen already emits. Every `params:` slot now points at a generated
-// `…ParamsSchema` and these were left behind, referenced by nothing but their
+// codegen already emits. Every method's schemas now come from the generated
+// registration table (src/generated/vgi-service.ts) and these were left behind, referenced by nothing but their
 // own import lines. A stale duplicate is worse than no duplicate: the copies
 // this SDK kept had drifted on `attach_opaque_data` nullability (45 generated
 // schemas say non-null, every copy said nullable) and on `type` being
 // dictionary-encoded utf8 rather than plain utf8, and the result was that a
-// CORRECT client got rejected at the very first catalog call. Import from
-// src/generated/vgi-protocol-schemas.ts instead of reviving one.
+// CORRECT client got rejected at the very first catalog call. Never revive one:
+// the registration table is generated, schemas and all.