@query-farm/vgi 0.30.0 → 0.32.0

package/dist/protocol/carried-init-request.d.ts

@@ -0,0 +1,28 @@
+import type { InitRequest } from "./types.js";
+/** Pack an init request's IPC bytes for the cursor: `u8 codec | payload`. */
+export declare function packInitRequest(ipc: Uint8Array): Uint8Array;
+/** What a continuation needs from the carried init request. */
+export interface CarriedInitRequest {
+    /**
+     * The parsed request -- a fresh top-level object with a fresh `bind_call`
+     * each call, so the per-turn assignments the dispatcher makes (split
+     * payloads) never reach the shared parse. The nested values (Arrow
+     * schemas and batches, arguments) are shared and must be treated as
+     * read-only, as they always were.
+     */
+    request: InitRequest;
+    /** The raw bind-call IPC bytes, which the split-token fingerprint hashes. */
+    bindCallIpc: Uint8Array;
+}
+/**
+ * Parse the init request a cursor carries (as packed by
+ * {@link packInitRequest}), from the process memo when this stream's turns have
+ * been here before.
+ */
+export declare function parseCarriedInitRequest(packed: Uint8Array): CarriedInitRequest;
+/** Cumulative parse / memo-hit counts for this process (observability and tests). */
+export declare function carriedInitRequestStats(): {
+    parses: number;
+    hits: number;
+    entries: number;
+};

package/dist/protocol/dispatch.d.ts

@@ -5,13 +5,6 @@ export interface ProtocolConfig {
     registry: FunctionRegistry;
     catalogInterface?: CatalogInterface;
     catalogName?: string;
-    /**
-     * Recover accumulated exchange state from FINALIZE init_opaque_data.
-     * For HTTP transport, this unpacks the state token that the C++ extension
-     * passes from the last INPUT exchange to the FINALIZE init request.
-     * Returns the deserialized VGI dispatch state object (with userState field).
-     */
-    recoverExchangeState?: (opaqueData: Uint8Array) => any;
     /**
      * AEAD signing key for sealing catalog opaque-data envelopes. Pass the same
      * 32-byte key used for HTTP state tokens. When omitted (subprocess / unix
@@ -20,4 +13,30 @@ export interface ProtocolConfig {
      */
     signingKey?: Uint8Array;
 }
+/**
+ * Wire name of the VGI protocol: the `vgi_rpc.protocol` routing key and the
+ * `{protocol}` HTTP path segment.
+ *
+ * The name carries the major version, so an incompatible major is a
+ * *different* protocol and therefore a 404 — an answer every proxy, WAF and
+ * load balancer understands without an Arrow parser, and one that lets
+ * `vgi.v2` and a future `vgi.v3` be served side by side while clients migrate.
+ * 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
+ * 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`,
+ * this port `vgi` — so no client could address them all. The canonical name is
+ * decided in vgi-python and emitted by the DuckDB extension; this is that same
+ * string, not an independent choice.
+ *
+ * Since `@query-farm/vgi-rpc` 0.24.0 the name is also bound into the AEAD
+ * associated data of every state and call token (`TokenScope.protocol`), so a
+ * caller that opens a token minted by this protocol has to name it. Exported
+ * 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 declare function buildVgiProtocol(config: ProtocolConfig): Protocol;

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

@@ -2,7 +2,6 @@ import { Protocol } from "@query-farm/vgi-rpc";
 import type { FunctionRegistry } from "../../functions/registry.js";
 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

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

@@ -1,6 +1,5 @@
 import { type VgiSchema } from "../../arrow/index.js";
 import type { OverloadContext } from "../../functions/registry.js";
-import type { InitRequest } from "../types.js";
 export declare const RESULT_BINARY_SCHEMA: VgiSchema;
 export declare const REQUEST_PARAMS_SCHEMA: VgiSchema;
 export declare const RESULT_BINARY_NULLABLE_SCHEMA: VgiSchema;
@@ -29,9 +28,3 @@ export declare function overloadContext(req: {
 }, catalogInterface?: {
     catalogNameForAttach(a: Uint8Array): string | null;
 }): OverloadContext;
-/**
- * Recover accumulated exchange state from a FINALIZE init request.
- * For HTTP transport, this unpacks the state token that the C++ extension
- * passes from the last INPUT exchange to the FINALIZE init request.
- */
-export declare function recoverFinalizeState(request: InitRequest, recoverExchangeState: ((opaqueData: Uint8Array) => any) | undefined): any;

package/dist/protocol/state-serializer.d.ts

@@ -1,6 +1,12 @@
 import { type VgiDataType } from "../arrow/index.js";
 import type { StateSerializer } from "@query-farm/vgi-rpc";
-/** Schema for the exchange state carried in HTTP state tokens. */
+/**
+ * The fields of the exchange state an HTTP cursor carries, by name and type.
+ *
+ * Descriptive: {@link arrowStateSerializer} writes them as a flat binary frame
+ * (see there), not as an Arrow batch of this schema. Kept exported for API
+ * stability.
+ */
 export declare const EXCHANGE_STATE_SCHEMA: import("../index.core.js").VgiSchema;
 /** Infer an Arrow DataType from a JS value for user state serialization. */
 export declare function inferFieldType(value: any): VgiDataType;
@@ -19,5 +25,26 @@ export declare function serializeUserState(userState: any): Uint8Array | null;
  * Reconstructs a plain JS object, preserving BigInt for Int64 columns.
  */
 export declare function deserializeUserState(bytes: Uint8Array | null): any;
-/** Arrow IPC state serializer — stores all data as native binary columns. */
+/**
+ * The HTTP exchange state serializer: what a stream's cursor carries between
+ * turns.
+ *
+ * A flat, versioned binary frame, not an Arrow batch. The cursor is built and
+ * parsed on every turn of every HTTP stream, and wrapping eight scalars in a
+ * one-row Arrow batch cost ~0.4 ms a turn (a generic column builder per field,
+ * an IPC schema message each way) plus ~1 KB of framing that was then sealed
+ * and base64-encoded twice per turn. The fields are the ones
+ * {@link EXCHANGE_STATE_SCHEMA} names; `user_state` stays Arrow IPC inside the
+ * frame, because it carries typed user values.
+ *
+ * Layout (little-endian): `u8 version | u8 flags | f64 max_workers |
+ * bytes function_name | bytes init_request | bytes execution_id |
+ * [bytes opaque_data] [bytes user_state] [bytes filter_history]`, where
+ * `bytes` is `u32 length, payload` and a bracketed field is present only when
+ * its flag bit is set. The frame never leaves this worker unsealed, so the
+ * version byte exists to turn a token minted by another build into a clean
+ * refusal rather than a misread.
+ *
+ * The name is kept for API stability; the Arrow in it is the user state.
+ */
 export declare const arrowStateSerializer: StateSerializer;