@query-farm/vgi 0.42.0 → 0.44.0

package/dist/protocol/dispatch.d.ts

@@ -1,6 +1,7 @@
-import { Protocol } from "@query-farm/vgi-rpc";
+import type { Protocol } from "@query-farm/vgi-rpc";
 import type { FunctionRegistry } from "../functions/registry.js";
 import type { CatalogInterface } from "../catalog/interface.js";
+import { VGI_PROTOCOL_NAME, type VgiService } from "../generated/vgi-service.js";
 export interface ProtocolConfig {
     registry: FunctionRegistry;
     catalogInterface?: CatalogInterface;
@@ -24,7 +25,8 @@ export interface ProtocolConfig {
  * That matters for this consumer specifically: the DuckDB extension ships to
  * users and cannot be flag-dayed.
  *
- * Declared rather than derived. Until the transports made the routing key
+ * Declared rather than derived, and now generated with the method table
+ * (src/generated/vgi-service.ts). Until the transports made the routing key
  * required, each implementation's wire name defaulted to whatever its local
  * type was called, which left the six ports disagreeing four ways — Python
  * `VgiProtocol`, Java and C# `VgiService`, Go the framework default `Service`,
@@ -38,18 +40,25 @@ export interface ProtocolConfig {
  * so the HTTP entry points build that scope from the same constant the
  * protocol is registered under rather than a second copy of the literal.
  */
-export declare const VGI_PROTOCOL_NAME = "vgi.v2";
+export { VGI_PROTOCOL_NAME };
 /**
  * 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).
+ * with the generated UNIMPLEMENTED default (src/generated/vgi-service.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 declare const VGI_V2_PROTOCOL_HASH = "774cb80090d71ea76d09aa311b9cda4ca4c33c3bf72c43242eb6dc87b6f79ce5";
+/**
+ * This worker's `vgi.v2` implementation: the generated UNIMPLEMENTED default
+ * for every method, overridden by the handler groups for what this SDK serves.
+ */
+export declare function buildVgiService(config: ProtocolConfig): VgiService;
+/** The `vgi.v2` protocol, registered from the generated table with {@link buildVgiService}. */
 export declare function buildVgiProtocol(config: ProtocolConfig): Protocol;

package/dist/protocol/handlers/aggregate.d.ts

@@ -1,3 +1,4 @@
-import { Protocol } from "@query-farm/vgi-rpc";
+import type { VgiService } from "../../generated/vgi-service.js";
 import type { FunctionRegistry } from "../../functions/registry.js";
-export declare function registerAggregateMethods(protocol: Protocol, registry: FunctionRegistry): void;
+/** The aggregate lifecycle's `vgi.v2` handlers. */
+export declare function aggregateHandlers(registry: FunctionRegistry): Partial<VgiService>;

package/dist/protocol/handlers/catalog/admin.d.ts

@@ -1,3 +1,3 @@
-import { Protocol } from "@query-farm/vgi-rpc";
+import type { VgiService } from "../../../generated/vgi-service.js";
 import { type GetCatalog } from "./shared.js";
-export declare function registerCatalogAdminMethods(protocol: Protocol, getCatalog: GetCatalog, signingKey?: Uint8Array): void;
+export declare function catalogAdminHandlers(getCatalog: GetCatalog, signingKey?: Uint8Array): Partial<VgiService>;

package/dist/protocol/handlers/catalog/index.d.ts

@@ -1,3 +1,4 @@
-import { Protocol } from "@query-farm/vgi-rpc";
 import type { CatalogInterface } from "../../../catalog/interface.js";
-export declare function registerCatalogMethods(protocol: Protocol, catalog: CatalogInterface | undefined, _catalogName: string | undefined, signingKey?: Uint8Array): void;
+import type { VgiService } from "../../../generated/vgi-service.js";
+/** The catalog_* `vgi.v2` handlers, over *catalog* (or `NoCatalogError` without one). */
+export declare function catalogHandlers(catalog: CatalogInterface | undefined, signingKey?: Uint8Array): Partial<VgiService>;

package/dist/protocol/handlers/catalog/index_methods.d.ts

@@ -1,3 +1,3 @@
-import { Protocol } from "@query-farm/vgi-rpc";
+import type { VgiService } from "../../../generated/vgi-service.js";
 import { type GetCatalog } from "./shared.js";
-export declare function registerCatalogIndexMethods(protocol: Protocol, getCatalog: GetCatalog, signingKey?: Uint8Array): void;
+export declare function catalogIndexHandlers(getCatalog: GetCatalog, signingKey?: Uint8Array): Partial<VgiService>;

package/dist/protocol/handlers/catalog/macro.d.ts

@@ -1,3 +1,3 @@
-import { Protocol } from "@query-farm/vgi-rpc";
+import type { VgiService } from "../../../generated/vgi-service.js";
 import { type GetCatalog } from "./shared.js";
-export declare function registerCatalogMacroMethods(protocol: Protocol, getCatalog: GetCatalog, signingKey?: Uint8Array): void;
+export declare function catalogMacroHandlers(getCatalog: GetCatalog, signingKey?: Uint8Array): Partial<VgiService>;

package/dist/protocol/handlers/catalog/shared.d.ts

@@ -1,5 +1,4 @@
-import { type VgiSchema } from "../../../arrow/index.js";
-import { Protocol, type AuthContext, type CallContext } from "@query-farm/vgi-rpc";
+import type { AuthContext, CallContext } from "@query-farm/vgi-rpc";
 import type { CatalogInterface } from "../../../catalog/interface.js";
 export type GetCatalog = () => CatalogInterface;
 /**
@@ -40,17 +39,12 @@ export declare function shardKeyForAttach(sealed: Uint8Array | undefined, auth:
  */
 export declare function sealTransaction(plaintext: Uint8Array, attachEnvelope: Uint8Array, auth: AuthContext | undefined, signingKey: Uint8Array | undefined): Promise<Uint8Array>;
 /**
- * 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.
- */
-export declare function catalogUnary(protocol: Protocol, signingKey: Uint8Array | undefined, name: string, config: {
-    params: unknown;
-    result: unknown;
-    handler: (params: Record<string, any>, ctx: CallContext) => unknown;
-    doc?: string;
-}): void;
+ * 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 declare function catalogHandler<R>(signingKey: Uint8Array | undefined, handler: (params: Record<string, any>, ctx: CallContext) => R | Promise<R>): (params: object, ctx: CallContext) => Promise<R>;
 export declare function makeGetCatalog(catalog: CatalogInterface | undefined): GetCatalog;
 /**
  * Decode the `options` field of a catalog_attach request into a plain
@@ -59,4 +53,3 @@ export declare function makeGetCatalog(catalog: CatalogInterface | undefined): G
  * one row with the value. Returns `{}` for null / empty input.
  */
 export declare function decodeOptionsBatch(bytes: any): Record<string, unknown>;
-export declare const emptyResultSchema: VgiSchema;

package/dist/protocol/handlers/catalog/table.d.ts

@@ -1,3 +1,3 @@
-import { Protocol } from "@query-farm/vgi-rpc";
+import type { VgiService } from "../../../generated/vgi-service.js";
 import { type GetCatalog } from "./shared.js";
-export declare function registerCatalogTableMethods(protocol: Protocol, getCatalog: GetCatalog, signingKey?: Uint8Array): void;
+export declare function catalogTableHandlers(getCatalog: GetCatalog, signingKey?: Uint8Array): Partial<VgiService>;

package/dist/protocol/handlers/catalog/view.d.ts

@@ -1,3 +1,3 @@
-import { Protocol } from "@query-farm/vgi-rpc";
+import type { VgiService } from "../../../generated/vgi-service.js";
 import { type GetCatalog } from "./shared.js";
-export declare function registerCatalogViewMethods(protocol: Protocol, getCatalog: GetCatalog, signingKey?: Uint8Array): void;
+export declare function catalogViewHandlers(getCatalog: GetCatalog, signingKey?: Uint8Array): Partial<VgiService>;

package/dist/protocol/handlers/function.d.ts

@@ -1,4 +1,4 @@
-import { Protocol } from "@query-farm/vgi-rpc";
+import { type VgiService } from "../../generated/vgi-service.js";
 import type { FunctionRegistry } from "../../functions/registry.js";
 export interface FunctionHandlerConfig {
     registry: FunctionRegistry;
@@ -23,4 +23,5 @@ export interface FunctionHandlerConfig {
         version?(attach: Uint8Array, txn?: Uint8Array): number | Promise<number>;
     };
 }
-export declare function registerFunctionMethods(protocol: Protocol, config: FunctionHandlerConfig): void;
+/** The per-function lifecycle's `vgi.v2` handlers. */
+export declare function functionHandlers(config: FunctionHandlerConfig): Partial<VgiService>;

package/dist/protocol/handlers/shared.d.ts

@@ -2,7 +2,6 @@ import { type VgiSchema } from "../../arrow/index.js";
 import type { OverloadContext } from "../../functions/registry.js";
 export declare const RESULT_BINARY_SCHEMA: VgiSchema;
 export declare const REQUEST_PARAMS_SCHEMA: VgiSchema;
-export declare const RESULT_BINARY_NULLABLE_SCHEMA: VgiSchema;
 /**
  * Unwrap a "request" Binary column: deserialize the inner Arrow IPC batch
  * and return flat columns as a dict (row 0).
@@ -12,7 +11,8 @@ export declare function unwrapRequest(requestBytes: any): Record<string, any>;
 export declare function normalizeRequestSchemaPaths(params: Record<string, any>): void;
 /**
  * Wrap a dict of values into a single "result" Binary column.
- * Builds a 1-row batch from the values using the given schema,
+ * Builds a 1-row batch from the values using the given schema (conformed to
+ * the protocol's container rules, see `conformRecord`),
  * serializes it to IPC bytes, and returns { result: bytes }.
  */
 export declare function wrapResult(values: Record<string, any>, innerSchema: VgiSchema | import("../../arrow/index.js").VgiSchema): {

package/dist/protocol/handlers/table-buffering.d.ts

@@ -1,3 +1,4 @@
-import { Protocol } from "@query-farm/vgi-rpc";
+import type { VgiService } from "../../generated/vgi-service.js";
 import type { FunctionRegistry } from "../../functions/registry.js";
-export declare function registerTableBufferingMethods(protocol: Protocol, registry: FunctionRegistry, signingKey?: Uint8Array): void;
+/** The table_buffering lifecycle's `vgi.v2` handlers. */
+export declare function tableBufferingHandlers(registry: FunctionRegistry, signingKey?: Uint8Array): Partial<VgiService>;

package/dist/protocol/handlers/unimplemented.d.ts

@@ -1,17 +1,4 @@
-import { type Protocol } from "@query-farm/vgi-rpc";
-import type { VgiSchema } from "../../arrow/index.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 declare const UNIMPLEMENTED_METHODS: readonly UnimplementedMethod[];
-/** The message every unimplemented method answers with. */
-export declare function unimplementedMessage(method: string): string;
-export declare function registerUnimplementedMethods(protocol: Protocol): void;
-export {};
+import { type VgiMethodSpec } from "../../generated/vgi-service.js";
+export { unimplementedMessage } from "../../generated/vgi-service.js";
+/** The vgi.v2 methods (of the reference's 72) this SDK leaves at the generated default. */
+export declare const UNIMPLEMENTED_METHODS: readonly VgiMethodSpec[];

package/dist/protocol/serializers/shared.d.ts

@@ -7,6 +7,7 @@ import { type VgiSchema, type VgiBatch } from "../../arrow/index.js";
 export declare function toUint8Array(val: any): Uint8Array;
 /**
  * Build a single-row RecordBatch from a {fieldName: value} dict matching the
- * given schema. Auto-coerces JS numbers to BigInt for Int64 fields.
+ * given schema. Auto-coerces JS numbers to BigInt for Int64 fields, and
+ * applies the protocol's container rules (`conformRecord`).
  */
 export declare function buildSingleRowBatch(schema: VgiSchema, values: Record<string, any>): VgiBatch;

package/dist/rpc-server.d.ts

@@ -31,13 +31,13 @@ export interface HostingOptions {
      *
      * Each needs a distinct wire name, which may not be `vgi.v2` and may not
      * use the reserved `vgi_rpc.` prefix: reflection is hosted automatically and
-     * `vgi_rpc.Identity.v1` is enabled through {@link resolveToken} /
+     * `vgi_rpc.Identity.v2` is enabled through {@link resolveToken} /
      * {@link mintGrant}. Violations are a startup error naming this hook.
      */
     hostedProtocols?: () => Iterable<Protocol>;
     /**
      * Resolve an opaque bearer credential to the identity it authenticates as.
-     * Supplying it hosts `vgi_rpc.Identity.v1`'s `introspect_token` -- on HTTP,
+     * Supplying it hosts `vgi_rpc.Identity.v2`'s `introspect_token` -- on HTTP,
      * the transport that authenticates callers. Absent, the method is absent
      * (not hosted-and-refusing), which keeps a dependency upgrade from growing a
      * credential-to-identity oracle on every existing worker.