@query-farm/vgi 0.31.0 → 0.33.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

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;