@query-farm/vgi 0.30.0 → 0.32.0

package/src/protocol/carried-init-request.ts

@@ -0,0 +1,139 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// The init request an HTTP stream carries in its cursor: packed once, parsed
+// once per process.
+//
+// An HTTP stream has no memory between turns, so its cursor carries the whole
+// init request (~9 KB of Arrow IPC for a DuckDB scan: the bind call with its
+// arguments, settings and sealed attach, the output schema, the filter
+// snapshot) and every turn used to re-parse it: the IPC read, the scalar-dict
+// walk and the nested bind-call / schema / filter reads cost ~0.9 ms, the
+// largest VGI-side share of the ~4 ms a 1000-row turn took. The cursor is also
+// re-sealed and base64-encoded on every turn, so its size is paid twice per
+// turn in AEAD and base64 work, and twice again on the wire.
+//
+// - `packInitRequest` zstd-compresses the request once, at /init (~9 KB ->
+//   ~2.6 KB), behind a one-byte codec tag. A runtime without synchronous zstd
+//   stores it raw.
+// - `parseCarriedInitRequest` keeps a small per-process LRU from the packed
+//   bytes to their parse. It is a pure memo of a pure function: the key is the
+//   exact bytes (hash, then a full comparison), so a hit returns precisely
+//   what parsing those bytes would -- and those bytes came out of a cursor the
+//   worker sealed. Nothing principal-dependent is cached: the split tokens and
+//   the sealed attach are still opened, under the caller, on every turn. A
+//   miss (cold process, eviction, another replica's stream) parses as before,
+//   so correctness never depends on a hit.
+
+import { deserializeBatch } from "../arrow/index.js";
+import { batchToScalarDict } from "../util/arrow/index.js";
+import { zstdSync } from "../util/zstd-sync.js";
+import { deserializeInitRequest } from "./serialize.js";
+import type { InitRequest } from "./types.js";
+
+const RAW = 0;
+const ZSTD = 1;
+
+/** Pack an init request's IPC bytes for the cursor: `u8 codec | payload`. */
+export function packInitRequest(ipc: Uint8Array): Uint8Array {
+  const codec = zstdSync();
+  const compressed = codec ? codec.compress(ipc) : null;
+  const useZstd = compressed !== null && compressed.byteLength < ipc.byteLength;
+  const payload = useZstd ? compressed! : ipc;
+  const packed = new Uint8Array(payload.byteLength + 1);
+  packed[0] = useZstd ? ZSTD : RAW;
+  packed.set(payload, 1);
+  return packed;
+}
+
+function unpackInitRequest(packed: Uint8Array): Uint8Array {
+  if (packed.byteLength === 0) throw new Error("state token carries no init request");
+  switch (packed[0]) {
+    case RAW:
+      return packed.slice(1);
+    case ZSTD: {
+      const codec = zstdSync();
+      if (!codec) {
+        throw new Error(
+          "state token carries a zstd-compressed init request, and this runtime has no synchronous zstd " +
+            "(it was minted by a worker running under Bun or Node >= 22.15 with the same signing key)",
+        );
+      }
+      return codec.decompress(packed.subarray(1));
+    }
+    default:
+      throw new Error(`state token carries an init request with unknown codec ${packed[0]}`);
+  }
+}
+
+/** 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;
+}
+
+interface Parsed {
+  packed: Uint8Array;
+  request: InitRequest;
+  bindCallIpc: Uint8Array;
+}
+
+/** Streams whose parse a process keeps. Past this, the least recently used is dropped. */
+const MAX_ENTRIES = 128;
+const parsed = new Map<number, Parsed>();
+const stats = { parses: 0, hits: 0 };
+
+/** FNV-1a over the bytes, folded with the length. */
+function hashBytes(bytes: Uint8Array): number {
+  let h = 0x811c9dc5 ^ bytes.byteLength;
+  for (let i = 0; i < bytes.byteLength; i++) {
+    h ^= bytes[i];
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.byteLength !== b.byteLength) return false;
+  for (let i = 0; i < a.byteLength; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/**
+ * 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 function parseCarriedInitRequest(packed: Uint8Array): CarriedInitRequest {
+  const key = hashBytes(packed);
+  let entry = parsed.get(key);
+  if (entry && sameBytes(entry.packed, packed)) {
+    // Refresh its recency.
+    parsed.delete(key);
+    parsed.set(key, entry);
+    stats.hits++;
+  } else {
+    const dict = batchToScalarDict(deserializeBatch(unpackInitRequest(packed)));
+    stats.parses++;
+    entry = { packed: packed.slice(), request: deserializeInitRequest(dict), bindCallIpc: dict.bind_call };
+    // A hash collision simply replaces the other stream's entry.
+    parsed.delete(key);
+    if (parsed.size >= MAX_ENTRIES) parsed.delete(parsed.keys().next().value!);
+    parsed.set(key, entry);
+  }
+  return {
+    request: { ...entry.request, bind_call: { ...entry.request.bind_call } },
+    bindCallIpc: entry.bindCallIpc,
+  };
+}
+
+/** Cumulative parse / memo-hit counts for this process (observability and tests). */
+export function carriedInitRequestStats(): { parses: number; hits: number; entries: number } {
+  return { ...stats, entries: parsed.size };
+}

package/src/protocol/dispatch.ts

@@ -20,13 +20,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
@@ -36,12 +29,38 @@ 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 const VGI_PROTOCOL_NAME = "vgi.v2";
+
 export function buildVgiProtocol(config: ProtocolConfig): Protocol {
-  const protocol = new Protocol("vgi", { protocolVersion: "2.0.0" });
+  const protocol = new Protocol(VGI_PROTOCOL_NAME, { protocolVersion: "2.0.0" });
 
   registerFunctionMethods(protocol, {
     registry: config.registry,
-    recoverExchangeState: config.recoverExchangeState,
     signingKey: config.signingKey,
     catalogInterface: config.catalogInterface,
   });

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

@@ -4,7 +4,8 @@
 
 import { type VgiSchema, schema, type VgiField, field, type VgiDataType, binary, utf8, bool } from "../../../arrow/index.js";
 import { Protocol, type CallContext } from "@query-farm/vgi-rpc";
-import { encodeSchemaInfo, encodeTableInfo, encodeViewInfo, encodeFunctionInfo, encodeCatalogInfo } from "../../../generated/vgi-client.js";
+import { encodeSchemaInfo, encodeTableInfo, encodeViewInfo, encodeCatalogInfo } from "../../../generated/vgi-client.js";
+import { encodeFunctionInfoOnce } from "../../../catalog/item-encoding.js";
 import { encodeCopyFromFormatInfo } from "../../../catalog/interface.js";
 import {
   CatalogAttachParamsSchema,
@@ -360,8 +361,10 @@ export function registerCatalogAdminMethods(protocol: Protocol, getCatalog: GetC
         decodeDictValue(params.type),
         params.transaction_opaque_data ? toUint8Array(params.transaction_opaque_data) : undefined
       );
+      // A frozen item (a descriptor catalog's cached listing) is encoded once;
+      // anything else is encoded per call, as before (see item-encoding.ts).
       return wrapResult({
-        items: funcs.map((f) => encodeFunctionInfo(f)),
+        items: funcs.map((f) => encodeFunctionInfoOnce(f)),
       }, CatalogSchemaContentsFunctionsResultSchema);
     },
   });

package/src/protocol/handlers/function.ts

@@ -37,9 +37,9 @@ import {
   unwrapRequest,
   wrapResult,
   overloadContext,
-  recoverFinalizeState,
 } from "./shared.js";
 import { GLOBAL_INIT_RESPONSE_SCHEMA } from "../serializers/init.js";
+import { parseCarriedInitRequest } from "../carried-init-request.js";
 import { openAttach } from "./catalog/shared.js";
 import { currentRequestAuth } from "../../request-auth.js";
 import { batchFromColumns, serializeBatch } from "../../util/arrow/index.js";
@@ -61,7 +61,6 @@ import {
 
 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
@@ -314,11 +313,11 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
       // FunctionStorage (e.g. Cloudflare DO).
       const initResponse = await func.globalInit(request);
 
-      // For FINALIZE over HTTP, recover accumulated INPUT state from init_opaque_data.
-      // The C++ extension passes the last exchange state token as init_opaque_data.
-      const accumulatedState = recoverFinalizeState(request, config.recoverExchangeState);
-
-      const handlers = func.createStreamHandlers(request, initResponse, accumulatedState);
+      // A FINALIZE stream reads its accumulated states from storage, where
+      // every INPUT turn persisted them. Its `init_opaque_data` is the primary
+      // init's opaque data echoed back (vgi-python's InitRequest), never a
+      // cursor, so nothing here opens it.
+      const handlers = func.createStreamHandlers(request, initResponse);
 
       // Initialize the appropriate handler
       let handlerState: HandlerState | undefined;
@@ -384,9 +383,10 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
         // Deserialized from token — reconstruct from serializable refs.
         // Infrastructure (processParams, BoundStorage) is recreated fresh.
         // Mutable user state is merged from state.userState.
-        const initRequestBatch = deserializeBatch(state.initRequestIpc);
-        const initRequestDict = batchToScalarDict(initRequestBatch);
-        const request = deserializeInitRequest(initRequestDict);
+        // Parsed once per process per stream (carried-init-request.ts): the
+        // cursor carries the packed request unchanged on every turn.
+        const carried = parseCarriedInitRequest(state.initRequestPacked);
+        const request = carried.request;
         // Re-derive the split payloads. The cursor carries the wire request,
         // which has `split_tokens` but not the opened `split_payloads` — that
         // field only ever existed in memory on the init turn. Without this a
@@ -399,7 +399,7 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
         // pre-deserialization blob from the cursor — handing it the decoded
         // object hashes a different shape and every token fails as
         // SPLIT_TOKEN_INVALID "minted for a different bind".
-        await resolveSplitPayloads(request, { bind_call: initRequestDict.bind_call }, {
+        await resolveSplitPayloads(request, { bind_call: carried.bindCallIpc }, {
           // Same principal the tokens were sealed under. The exchange dispatch
           // gets no ctx (see stripAttach above), so the request-scoped identity
           // is the only source — opening under the anonymous tail would fail
@@ -418,10 +418,10 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
           opaque_data: opaqueData,
         };
 
-        // Recover accumulated state for FINALIZE phase from initOpaqueData
-        const recoveredState = recoverFinalizeState(request, config.recoverExchangeState);
-
-        handlers = func.createStreamHandlers(request, initResponse, recoveredState);
+        // The cursor's compacted dynamic-filter history: without it every turn
+        // after the one that received a delta would scan under the init
+        // snapshot again, because the extension sends each delta only once.
+        handlers = func.createStreamHandlers(request, initResponse, state.filterHistory ?? null);
         if (handlers.producerInit) {
           handlerState = handlers.producerInit();
         } else if (handlers.exchangeInit) {
@@ -453,6 +453,9 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
       if (handlerState?.state !== undefined) {
         state.userState = handlerState!.state;
       }
+      // And the dynamic-filter history this turn left (compacted: bounded by
+      // the number of predicate ids, not the number of turns).
+      state.filterHistory = handlerState?.filterHistory ?? null;
     },
     headerSchema: initHeaderSchema,
     headerInit: (params: any, state: any, ctx: any) => {

package/src/protocol/handlers/shared.ts

@@ -5,8 +5,6 @@ import { type VgiSchema, schema, type VgiField, field, type VgiDataType, binary
 import type { OverloadContext } from "../../functions/registry.js";
 import { batchToScalarDict, deserializeBatch, serializeBatch, batchFromColumns } from "../../util/arrow/index.js";
 import { toUint8Array } from "../../util/bytes.js";
-import { TableInOutPhase } from "../../types.js";
-import type { InitRequest } from "../types.js";
 import { normalizeSchemaPath } from "../../schema-path.js";
 
 // The Python vgi-rpc framework wraps ALL non-void unary results in a single
@@ -91,23 +89,3 @@ export function overloadContext(
     catalogName,
   };
 }
-
-/**
- * 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 function recoverFinalizeState(
-  request: InitRequest,
-  recoverExchangeState: ((opaqueData: Uint8Array) => any) | undefined,
-): any {
-  if (request.phase === TableInOutPhase.FINALIZE && request.init_opaque_data && recoverExchangeState) {
-    try {
-      const recovered = recoverExchangeState(request.init_opaque_data);
-      return recovered?.userState;
-    } catch (e: any) {
-      throw new Error(`Failed to recover FINALIZE state from init_opaque_data: ${e.message}`);
-    }
-  }
-  return undefined;
-}

package/src/protocol/state-serializer.ts

@@ -1,7 +1,6 @@
 // Copyright 2025, 2026 Query Farm LLC - https://query.farm
-// Arrow IPC state serializer for HTTP transport.
-// Replaces JSON serialization with Arrow IPC for the exchange state token,
-// avoiding base64/hex overhead and staying consistent with the rest of the protocol.
+// State serializer for the HTTP transport: the exchange state an HTTP cursor
+// carries between turns, and the Arrow IPC encoding of user state inside it.
 
 import {
   type VgiDataType,
@@ -27,21 +26,42 @@ import {
 import { codecFor } from "../arrow/codec/registry.js";
 import type { StateSerializer } from "@query-farm/vgi-rpc";
 import { toUint8Array } from "../util/bytes.js";
+import { decodeFilterHistory, encodeFilterHistory } from "../filter-pushdown/history.js";
+import { packInitRequest } from "./carried-init-request.js";
 
-/** 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 const EXCHANGE_STATE_SCHEMA = makeSchema([
   field("function_name", binary(), false),
+  // The init request, packed by carried-init-request.ts (a codec byte, then
+  // the IPC bytes, zstd-compressed where the runtime can).
   field("init_request", binary(), false),
   field("execution_id", binary(), false),
   field("max_workers", int64(), false),
   field("opaque_data", binary(), true),
   field("is_producer", bool(), false),
   field("user_state", binary(), true),
+  // The stream's compacted dynamic-filter history (filter-pushdown/history.ts),
+  // null when no delta has been applied. Bounded by the number of predicate
+  // ids, so the token stays flat-sized however many turns the scan takes.
+  field("filter_history", binary(), true),
 ]);
 
 const TEXT_ENCODER = new TextEncoder();
 const TEXT_DECODER = new TextDecoder();
 
+/** Version byte of the exchange state frame (never 0xFF, the first byte of an Arrow IPC stream). */
+const STATE_FORMAT_VERSION = 1;
+const FLAG_PRODUCER = 1;
+const FLAG_OPAQUE_DATA = 2;
+const FLAG_USER_STATE = 4;
+const FLAG_FILTER_HISTORY = 8;
+
 /**
  * Child field name for an inferred list. Arrow matches list children by
  * position, not name, so this is cosmetic — but keeping it at Arrow's
@@ -187,49 +207,101 @@ export function deserializeUserState(bytes: Uint8Array | null): any {
   return result;
 }
 
-/** 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 const arrowStateSerializer: StateSerializer = {
   serialize(state: any): Uint8Array {
-    const columns: Record<string, any[]> = {
-      function_name: [TEXT_ENCODER.encode(state.functionName)],
-      init_request: [state.initRequestIpc],
-      execution_id: [state.executionId],
-      max_workers: [state.maxWorkers],
-      opaque_data: [state.opaqueData ?? null],
-      is_producer: [state.isProducer],
-      user_state: [serializeUserState(state.userState)],
-    };
-    const batch = batchFromColumns(columns, EXCHANGE_STATE_SCHEMA);
-    return serializeBatch(batch);
+    const functionName = TEXT_ENCODER.encode(state.functionName ?? "");
+    // Packed on the init turn (the only one holding the raw bytes); every
+    // continuation carries the packed bytes through unchanged.
+    const initRequest: Uint8Array = state.initRequestPacked ?? packInitRequest(state.initRequestIpc);
+    const executionId = toUint8Array(state.executionId);
+    const opaqueData = state.opaqueData != null ? toUint8Array(state.opaqueData) : null;
+    const userState = serializeUserState(state.userState);
+    const filterHistory = encodeFilterHistory(state.filterHistory);
+    const flags =
+      (state.isProducer ? FLAG_PRODUCER : 0) |
+      (opaqueData ? FLAG_OPAQUE_DATA : 0) |
+      (userState ? FLAG_USER_STATE : 0) |
+      (filterHistory ? FLAG_FILTER_HISTORY : 0);
+    const chunks = [functionName, initRequest, executionId];
+    if (opaqueData) chunks.push(opaqueData);
+    if (userState) chunks.push(userState);
+    if (filterHistory) chunks.push(filterHistory);
+    let size = 2 + 8;
+    for (const chunk of chunks) size += 4 + chunk.byteLength;
+    const out = new Uint8Array(size);
+    const view = new DataView(out.buffer);
+    out[0] = STATE_FORMAT_VERSION;
+    out[1] = flags;
+    view.setFloat64(2, Number(state.maxWorkers ?? 1), true);
+    let offset = 10;
+    for (const chunk of chunks) {
+      view.setUint32(offset, chunk.byteLength, true);
+      out.set(chunk, offset + 4);
+      offset += 4 + chunk.byteLength;
+    }
+    return out;
   },
 
   deserialize(bytes: Uint8Array): any {
-    const batch = deserializeBatch(bytes);
-    const fieldByName = new Map(batch.schema.fields.map((f) => [f.name, f]));
-    const get = (name: string) => {
-      const col = batch.getChild(name);
-      const f = fieldByName.get(name);
-      if (!col || !f) return null;
-      const type = f.type as unknown as VgiDataType;
-      return codecFor(type).canonicalToRich(readCanonicalValue(type, col, 0));
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (bytes.byteLength < 10 || bytes[0] !== STATE_FORMAT_VERSION) {
+      throw new Error("exchange state has an unknown format (minted by another build of this worker?)");
+    }
+    const flags = bytes[1];
+    const maxWorkers = view.getFloat64(2, true);
+    let offset = 10;
+    // Each field is copied out, not viewed: Arrow readers want a buffer of
+    // their own (byteOffset 0), and nothing should pin the whole frame.
+    const take = (): Uint8Array => {
+      if (offset + 4 > bytes.byteLength) throw new Error("exchange state is truncated");
+      const length = view.getUint32(offset, true);
+      offset += 4;
+      if (offset + length > bytes.byteLength) throw new Error("exchange state is truncated");
+      const chunk = bytes.slice(offset, offset + length);
+      offset += length;
+      return chunk;
     };
-
-    const isProducer = get("is_producer");
-    const opaqueDataRaw = get("opaque_data");
-    const fnNameRaw = get("function_name");
-
+    const functionName = TEXT_DECODER.decode(take());
+    const initRequestPacked = take();
+    const executionId = take();
+    const opaqueData = flags & FLAG_OPAQUE_DATA ? take() : null;
+    const userStateBytes = flags & FLAG_USER_STATE ? take() : null;
+    const filterHistoryBytes = flags & FLAG_FILTER_HISTORY ? take() : null;
+    if (offset !== bytes.byteLength) throw new Error("exchange state has trailing bytes");
+    const isProducer = (flags & FLAG_PRODUCER) !== 0;
     return {
-      functionName: fnNameRaw != null ? TEXT_DECODER.decode(toUint8Array(fnNameRaw)) : "",
-      initRequestIpc: toUint8Array(get("init_request")),
-      executionId: toUint8Array(get("execution_id")),
-      maxWorkers: Number(get("max_workers")),
-      opaqueData: opaqueDataRaw != null ? toUint8Array(opaqueDataRaw) : null,
+      functionName,
+      initRequestPacked,
+      executionId,
+      maxWorkers,
+      opaqueData,
       isProducer,
       // vgi-rpc dispatch reads __isProducer to choose producer vs exchange mode
       __isProducer: isProducer,
-      userState: deserializeUserState(
-        get("user_state") != null ? toUint8Array(get("user_state")) : null,
-      ),
+      userState: deserializeUserState(userStateBytes),
+      filterHistory: decodeFilterHistory(filterHistoryBytes),
     };
   },
 };

package/src/util/zstd-sync.ts

@@ -0,0 +1,50 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// Synchronous zstd, where the runtime has it.
+//
+// The state serializer is synchronous (vgi-rpc's StateSerializer contract), so
+// it cannot use the async helpers vgi-rpc exposes. Bun has
+// `Bun.zstdCompressSync`; Node >= 22.15 has `zlib.zstdCompressSync`, reached
+// from ESM through `process.getBuiltinModule`. Anything else (workerd, a
+// browser) gets `null` and callers fall back to storing bytes uncompressed.
+
+/** A synchronous zstd codec. */
+export interface ZstdSync {
+  compress(data: Uint8Array): Uint8Array;
+  decompress(data: Uint8Array): Uint8Array;
+}
+
+/** Level 3 is zstd's default: ~3.4x on an init request, ~50 us for 9 KB. */
+const LEVEL = 3;
+
+function resolveZstdSync(): ZstdSync | null {
+  const bun = (globalThis as any).Bun;
+  if (typeof bun?.zstdCompressSync === "function" && typeof bun?.zstdDecompressSync === "function") {
+    return {
+      compress: (data) => new Uint8Array(bun.zstdCompressSync(data, { level: LEVEL })),
+      // Copied into a fresh buffer: Arrow readers want byteOffset 0.
+      decompress: (data) => new Uint8Array(bun.zstdDecompressSync(data)),
+    };
+  }
+  let zlib: any = null;
+  try {
+    zlib = (globalThis as any).process?.getBuiltinModule?.("node:zlib") ?? null;
+  } catch {
+    zlib = null;
+  }
+  if (typeof zlib?.zstdCompressSync === "function" && typeof zlib?.zstdDecompressSync === "function") {
+    const params = { [zlib.constants.ZSTD_c_compressionLevel]: LEVEL };
+    return {
+      compress: (data) => new Uint8Array(zlib.zstdCompressSync(data, { params })),
+      decompress: (data) => new Uint8Array(zlib.zstdDecompressSync(data)),
+    };
+  }
+  return null;
+}
+
+let resolved: ZstdSync | null | undefined;
+
+/** This runtime's synchronous zstd codec, or `null` when it has none. */
+export function zstdSync(): ZstdSync | null {
+  if (resolved === undefined) resolved = resolveZstdSync();
+  return resolved;
+}