@query-farm/vgi 0.41.0 → 0.43.0

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

@@ -10,24 +10,16 @@
 // vgi-python's worker._load_table_buffering_params.
 
 import { deserializeBatch } from "../../arrow/index.js";
-import { Protocol } from "@query-farm/vgi-rpc";
+import type { VgiService } from "../../generated/vgi-service.js";
 import type { FunctionRegistry } from "../../functions/registry.js";
 import { toUint8Array } from "../../util/bytes.js";
 import { batchToScalarDict, batchToSecretDict } from "../../util/arrow/index.js";
 import {
-  TableBufferingCombineParamsSchema,
   TableBufferingCombineResultSchema,
-  TableBufferingDestructorParamsSchema,
   TableBufferingDestructorResultSchema,
-  TableBufferingProcessParamsSchema,
   TableBufferingProcessResultSchema,
 } from "../../generated/vgi-protocol-schemas.js";
-import {
-  REQUEST_PARAMS_SCHEMA,
-  RESULT_BINARY_SCHEMA,
-  unwrapRequest,
-  wrapResult,
-} from "./shared.js";
+import { unwrapRequest, wrapResult } from "./shared.js";
 import { openAttach } from "./catalog/shared.js";
 import {
   BoundStorage,
@@ -41,11 +33,11 @@ import {
 } from "../../functions/table-buffering.js";
 import { Arguments } from "../../arguments/arguments.js";
 
-export function registerTableBufferingMethods(
-  protocol: Protocol,
+/** The table_buffering lifecycle's `vgi.v2` handlers. */
+export function tableBufferingHandlers(
   registry: FunctionRegistry,
   signingKey?: Uint8Array,
-): void {
+): Partial<VgiService> {
   // `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
@@ -123,72 +115,62 @@ export function registerTableBufferingMethods(
   // ------------------------------------------------------------------------
   // table_buffering_process — sink one batch, return state_id (unary)
   // ------------------------------------------------------------------------
-  protocol.unary("table_buffering_process", {
-    params: TableBufferingProcessParamsSchema,
-    result: RESULT_BINARY_SCHEMA,
-    handler: async (rpcParams, ctx?: any) => {
-      const inner = unwrapRequest(rpcParams.request);
-      const clientLog = makeClientLog(ctx);
-      const { func, params } = await loadParams(inner, clientLog, ctx);
-      if (inner.batch_index != null) {
-        params.batchIndex = Number(inner.batch_index);
-      }
-      const batch = deserializeBatch(toUint8Array(inner.input_batch));
-      const stateId = await func.bufferingConfig.process(batch, params);
-      if (!(stateId instanceof Uint8Array)) {
-        throw new Error(
-          `${func.meta.name}.process() must return Uint8Array (the opaque state_id)`,
-        );
-      }
-      return wrapResult({ state_id: stateId }, TableBufferingProcessResultSchema);
-    },
-  });
+  const tableBufferingProcess: VgiService["tableBufferingProcess"] = async (rpcParams, ctx?: any) => {
+    const inner = unwrapRequest(rpcParams.request);
+    const clientLog = makeClientLog(ctx);
+    const { func, params } = await loadParams(inner, clientLog, ctx);
+    if (inner.batch_index != null) {
+      params.batchIndex = Number(inner.batch_index);
+    }
+    const batch = deserializeBatch(toUint8Array(inner.input_batch));
+    const stateId = await func.bufferingConfig.process(batch, params);
+    if (!(stateId instanceof Uint8Array)) {
+      throw new Error(
+        `${func.meta.name}.process() must return Uint8Array (the opaque state_id)`,
+      );
+    }
+    return wrapResult({ state_id: stateId }, TableBufferingProcessResultSchema);
+  };
 
   // ------------------------------------------------------------------------
   // table_buffering_combine — group/merge state_ids (unary)
   // ------------------------------------------------------------------------
-  protocol.unary("table_buffering_combine", {
-    params: TableBufferingCombineParamsSchema,
-    result: RESULT_BINARY_SCHEMA,
-    handler: async (rpcParams, ctx?: any) => {
-      const inner = unwrapRequest(rpcParams.request);
-      const clientLog = makeClientLog(ctx);
-      const { func, params } = await loadParams(inner, clientLog, ctx);
-      const stateIds = decodeBytesList(inner.state_ids);
-      const finalizeStateIds = await func.bufferingConfig.combine(stateIds, params);
-      const out = finalizeStateIds.map((fid, i) => {
-        if (!(fid instanceof Uint8Array)) {
-          throw new Error(
-            `${func.meta.name}.combine() returned non-Uint8Array finalize_state_id at index ${i}`,
-          );
-        }
-        return fid;
-      });
-      return wrapResult(
-        { finalize_state_ids: out },
-        TableBufferingCombineResultSchema,
-      );
-    },
-  });
+  const tableBufferingCombine: VgiService["tableBufferingCombine"] = async (rpcParams, ctx?: any) => {
+    const inner = unwrapRequest(rpcParams.request);
+    const clientLog = makeClientLog(ctx);
+    const { func, params } = await loadParams(inner, clientLog, ctx);
+    const stateIds = decodeBytesList(inner.state_ids);
+    const finalizeStateIds = await func.bufferingConfig.combine(stateIds, params);
+    const out = finalizeStateIds.map((fid, i) => {
+      if (!(fid instanceof Uint8Array)) {
+        throw new Error(
+          `${func.meta.name}.combine() returned non-Uint8Array finalize_state_id at index ${i}`,
+        );
+      }
+      return fid;
+    });
+    return wrapResult(
+      { finalize_state_ids: out },
+      TableBufferingCombineResultSchema,
+    );
+  };
 
   // ------------------------------------------------------------------------
   // table_buffering_destructor — best-effort end-of-query cleanup (unary)
   // ------------------------------------------------------------------------
-  protocol.unary("table_buffering_destructor", {
-    params: TableBufferingDestructorParamsSchema,
-    result: RESULT_BINARY_SCHEMA,
-    handler: async (rpcParams) => {
-      try {
-        const inner = unwrapRequest(rpcParams.request);
-        const executionId = toUint8Array(inner.execution_id);
-        const bound = new BoundStorage(defaultStorage, executionId);
-        await bound.executionClear();
-      } catch {
-        // Teardown path — swallow; the entry is wiped when the worker exits.
-      }
-      return wrapResult({}, TableBufferingDestructorResultSchema);
-    },
-  });
+  const tableBufferingDestructor: VgiService["tableBufferingDestructor"] = async (rpcParams) => {
+    try {
+      const inner = unwrapRequest(rpcParams.request);
+      const executionId = toUint8Array(inner.execution_id);
+      const bound = new BoundStorage(defaultStorage, executionId);
+      await bound.executionClear();
+    } catch {
+      // Teardown path — swallow; the entry is wiped when the worker exits.
+    }
+    return wrapResult({}, TableBufferingDestructorResultSchema);
+  };
+
+  return { tableBufferingProcess, tableBufferingCombine, tableBufferingDestructor };
 }
 
 function makeClientLog(ctx: any): (level: string, message: string) => void {

package/src/protocol/handlers/unimplemented.ts

@@ -0,0 +1,30 @@
+// 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). The registration and the UNIMPLEMENTED default for every
+// method are generated (src/generated/vgi-service.ts); this module only names
+// the methods whose generated default this worker leaves in place, so a test
+// can assert each one refuses with UNIMPLEMENTED.
+//
+// To implement one, add its handler to a group in this directory; it drops off
+// this list by itself.
+
+import { FunctionRegistry } from "../../functions/registry.js";
+import {
+  UNIMPLEMENTED_VGI_SERVICE,
+  VGI_V2_METHODS,
+  type VgiMethodSpec,
+} from "../../generated/vgi-service.js";
+import { buildVgiService } from "../dispatch.js";
+
+export { unimplementedMessage } from "../../generated/vgi-service.js";
+
+const service = buildVgiService({ registry: new FunctionRegistry() });
+
+/** The vgi.v2 methods (of the reference's 72) this SDK leaves at the generated default. */
+export const UNIMPLEMENTED_METHODS: readonly VgiMethodSpec[] = VGI_V2_METHODS.filter(
+  (m) => service[m.key] === UNIMPLEMENTED_VGI_SERVICE[m.key],
+);