@query-farm/vgi 0.6.0

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

@@ -0,0 +1,207 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// Unary handlers for the table_buffering (Sink+Source) lifecycle:
+//   table_buffering_process    — sink one input batch, return state_id
+//   table_buffering_combine    — group/merge state_ids -> finalize_state_ids
+//   table_buffering_destructor — best-effort end-of-query storage cleanup
+//
+// These RPCs carry no init context, so each cold-loads the init metadata that
+// the TABLE_BUFFERING init phase persisted to FunctionStorage (keyed by
+// execution_id), then rebuilds the user-facing TableBufferingParams. Mirrors
+// vgi-python's worker._load_table_buffering_params.
+
+import { deserializeBatch } from "../../arrow/index.js";
+import { Protocol } from "@query-farm/vgi-rpc";
+import type { FunctionRegistry } from "../../functions/registry.js";
+import { toUint8Array } from "../../util/bytes.js";
+import { batchToScalarDict, batchToSecretDict } from "../../util/arrow/index.js";
+import {
+  TableBufferingProcessResultSchema,
+  TableBufferingCombineResultSchema,
+  TableBufferingDestructorResultSchema,
+} from "../../generated/vgi-protocol-schemas.js";
+import {
+  REQUEST_PARAMS_SCHEMA,
+  RESULT_BINARY_SCHEMA,
+  unwrapRequest,
+  wrapResult,
+} from "./shared.js";
+import { openAttach } from "./catalog/shared.js";
+import {
+  BoundStorage,
+  storage as defaultStorage,
+  FrameworkNS,
+} from "../../functions/storage.js";
+import {
+  decodeBufferingInit,
+  type TableBufferingVgiFunction,
+  type TableBufferingParams,
+} from "../../functions/table-buffering.js";
+import { Arguments } from "../../arguments/arguments.js";
+
+export function registerTableBufferingMethods(
+  protocol: Protocol,
+  registry: FunctionRegistry,
+  signingKey?: Uint8Array,
+): void {
+  function resolveBuffering(name: string): TableBufferingVgiFunction {
+    const func = registry.get(name, {
+      arguments: new Arguments(),
+      inputSchema: null,
+      isScalar: false,
+    }) as any;
+    if (!func || func.kind !== "table_buffering") {
+      throw new Error(`Function '${name}' is not a table_buffering function`);
+    }
+    return func as TableBufferingVgiFunction;
+  }
+
+  // Cold-load init metadata + build TableBufferingParams from a unary request.
+  async function loadParams(
+    inner: Record<string, any>,
+    clientLog: (level: string, message: string) => void,
+    ctx: any,
+  ): Promise<{ func: TableBufferingVgiFunction; params: TableBufferingParams<any> }> {
+    const functionName: string = inner.function_name;
+    const executionId = toUint8Array(inner.execution_id);
+    // Unseal attach_opaque_data so combine()/process() see the SAME plaintext,
+    // attach-scoped bytes that bind()/init() and plain table functions see.
+    // Without this, on HTTP transport the buffering RPCs would scope persistent
+    // BoundStorage by the *sealed* envelope while reads scope by the plaintext,
+    // so attach-scoped state written in combine() is invisible to later reads.
+    const rawAttach = inner.attach_opaque_data ? toUint8Array(inner.attach_opaque_data) : null;
+    const attach =
+      rawAttach && rawAttach.length > 0
+        ? await openAttach(rawAttach, ctx?.auth, signingKey)
+        : rawAttach;
+    const transactionId = inner.transaction_id ? toUint8Array(inner.transaction_id) : null;
+
+    const func = resolveBuffering(functionName);
+    const bound = new BoundStorage(defaultStorage, executionId);
+    const payload = await bound.stateGet(
+      FrameworkNS.BUFFERING_INIT,
+      BoundStorage.packIntKey(-1),
+    );
+    if (payload == null) {
+      throw new Error(
+        `table_buffering: unknown execution_id ${hex(executionId)} ` +
+          `(init never ran or destructor already fired)`,
+      );
+    }
+    const { request } = decodeBufferingInit(payload);
+    const args = func.bufferingExtractArgs(request.bind_call);
+    const settings = batchToScalarDict(request.bind_call.settings);
+    const secrets = batchToSecretDict(request.bind_call.secrets);
+
+    const params: TableBufferingParams<any> = {
+      args,
+      initCall: request,
+      outputSchema: request.output_schema,
+      settings,
+      secrets,
+      storage: bound,
+      executionId,
+      attachId: attach ?? new Uint8Array(0),
+      transactionId,
+      function_name: functionName,
+      batchIndex: null,
+      clientLog,
+    };
+    return { func, params };
+  }
+
+  // ------------------------------------------------------------------------
+  // table_buffering_process — sink one batch, return state_id (unary)
+  // ------------------------------------------------------------------------
+  protocol.unary("table_buffering_process", {
+    params: REQUEST_PARAMS_SCHEMA,
+    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);
+    },
+  });
+
+  // ------------------------------------------------------------------------
+  // table_buffering_combine — group/merge state_ids (unary)
+  // ------------------------------------------------------------------------
+  protocol.unary("table_buffering_combine", {
+    params: REQUEST_PARAMS_SCHEMA,
+    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,
+      );
+    },
+  });
+
+  // ------------------------------------------------------------------------
+  // table_buffering_destructor — best-effort end-of-query cleanup (unary)
+  // ------------------------------------------------------------------------
+  protocol.unary("table_buffering_destructor", {
+    params: REQUEST_PARAMS_SCHEMA,
+    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);
+    },
+  });
+}
+
+function makeClientLog(ctx: any): (level: string, message: string) => void {
+  if (ctx && typeof ctx.clientLog === "function") {
+    return (level: string, message: string) => ctx.clientLog(level, message);
+  }
+  return () => {};
+}
+
+function decodeBytesList(raw: any): Uint8Array[] {
+  if (raw == null) return [];
+  const out: Uint8Array[] = [];
+  const iter: Iterable<any> = Array.isArray(raw)
+    ? raw
+    : typeof raw[Symbol.iterator] === "function"
+    ? raw
+    : [];
+  for (const entry of iter) {
+    if (entry == null) continue;
+    out.push(toUint8Array(entry));
+  }
+  return out;
+}
+
+function hex(buf: Uint8Array): string {
+  return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/protocol/serialize.ts

@@ -0,0 +1,23 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// Arrow serialization/deserialization for VGI protocol types.
+// Barrel re-export — implementations live in serializers/. The wire format
+// must match Python's ArrowSerializableDataclass output (identical field
+// names, types, and metadata).
+
+export { serializeArguments, deserializeArguments } from "./serializers/arguments.js";
+export {
+  serializeBindRequest,
+  deserializeBindRequest,
+  serializeBindResponse,
+  deserializeBindResponse,
+} from "./serializers/bind.js";
+export {
+  serializeInitRequest,
+  deserializeInitRequest,
+  serializeGlobalInitResponse,
+  deserializeGlobalInitResponse,
+} from "./serializers/init.js";
+export {
+  deserializeCardinalityRequest,
+  serializeTableCardinality,
+} from "./serializers/cardinality.js";

package/src/protocol/serializers/arguments.ts

@@ -0,0 +1,160 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// Arguments wire format — single-row Arrow batch with one "args" Struct
+// column whose children are named `positional_<i>` / `named_<name>`.
+// Matches Python's Arguments.serialize_to_bytes().
+
+import {
+  type VgiDataType,
+  type VgiField,
+  schema as makeSchema,
+  field,
+  struct as makeStruct,
+  utf8,
+  binary,
+  int64,
+  bool,
+  nullType,
+  isInt,
+  batchFromColumns,
+  serializeBatch,
+  deserializeBatch,
+  readCanonicalValue,
+} from "../../arrow/index.js";
+import { codecFor } from "../../arrow/codec/registry.js";
+import { Arguments } from "../../arguments/arguments.js";
+
+export function serializeArguments(args: Arguments): Uint8Array {
+  // Arguments are serialized as a single-row batch with one "args" Struct column.
+  // The struct has fields: "positional_0", "positional_1", ... and "named_<name>".
+
+  const structFields: VgiField[] = [];
+  const structValues: Record<string, any> = {};
+
+  for (let i = 0; i < args.positional.length; i++) {
+    const val = args.positional[i];
+    const fieldName = `positional_${i}`;
+    structFields.push(field(fieldName, inferScalarType(val), true));
+    structValues[fieldName] = val;
+  }
+
+  for (const [name, val] of args.named) {
+    const fieldName = `named_${name}`;
+    structFields.push(field(fieldName, inferScalarType(val), true));
+    structValues[fieldName] = val;
+  }
+
+  const structType = makeStruct(structFields);
+  const sch = makeSchema([field("args", structType, true)]);
+
+  // Coerce JS numbers to BigInt for Int64 children — both backends require
+  // BigInt at 64-bit width.
+  const structRow: Record<string, any> = {};
+  for (const f of structFields) {
+    let val = structValues[f.name];
+    if (isInt(f.type) && (f.type as any).bitWidth === 64 && typeof val === "number") {
+      val = BigInt(val);
+    }
+    structRow[f.name] = val;
+  }
+
+  const batch = batchFromColumns({ args: [structRow] }, sch);
+  return serializeBatch(batch);
+}
+
+function inferScalarType(val: any): VgiDataType {
+  if (val === null || val === undefined) return nullType();
+  if (typeof val === "string") return utf8();
+  if (typeof val === "boolean") return bool();
+  if (typeof val === "number") return int64();
+  if (typeof val === "bigint") return int64();
+  if (val instanceof Uint8Array || val instanceof ArrayBuffer) return binary();
+  return utf8(); // fallback (e.g. an Int32Array INTERVAL quad -> stringified)
+}
+
+export function deserializeArguments(bytes: Uint8Array): Arguments {
+  if (!bytes || bytes.length === 0) return new Arguments();
+
+  // Ensure we have a clean copy (not a view into a larger buffer)
+  const cleanBytes = bytes.byteOffset !== 0 || bytes.byteLength !== bytes.buffer.byteLength
+    ? new Uint8Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength))
+    : bytes;
+
+  const batch = deserializeBatch(cleanBytes);
+  const positional: any[] = [];
+  const named = new Map<string, any>();
+
+  if (batch.numRows === 0) {
+    return new Arguments(positional, named);
+  }
+
+  // Arguments are serialized as a single "args" Struct column.
+  // The struct has fields named "positional_0", "positional_1", etc.
+  // for positional args, and "named_<name>" for named args.
+  const argsCol = batch.getChild("args");
+  if (argsCol) {
+    // Extract per-positional types from the struct's children
+    const argsStructType = argsCol.type as any;
+    const structSchema = argsStructType.children
+      ? makeSchema(argsStructType.children)
+      : batch.schema;
+
+    // Read the args struct via the codec/canonical path (backend-agnostic,
+    // lossless, RICH) — surfaces as a plain { field: value } object.
+    const structType = argsCol.type as unknown as VgiDataType;
+    const structVal = codecFor(structType).canonicalToRich(
+      readCanonicalValue(structType, argsCol, 0),
+    ) as any;
+    if (structVal && typeof structVal === "object") {
+      const dict: Record<string, any> = structVal;
+      for (const [key, value] of Object.entries(dict)) {
+        if (key.startsWith("positional_")) {
+          const idx = parseInt(key.slice("positional_".length), 10);
+          while (positional.length <= idx) positional.push(null);
+          positional[idx] = value;
+        } else if (key.startsWith("named_")) {
+          const name = key.slice("named_".length);
+          named.set(name, value);
+        }
+      }
+    }
+    return new Arguments(positional, named, structSchema);
+  }
+
+  // Fallback: flat columns (legacy format - each field is a column)
+  const sch = batch.schema;
+  if (!sch || sch.fields.length === 0) {
+    return new Arguments(positional, named);
+  }
+
+  for (const f of sch.fields) {
+    const col = batch.getChild(f.name);
+    const ftype = f.type as unknown as VgiDataType;
+    const val = col
+      ? codecFor(ftype).canonicalToRich(readCanonicalValue(ftype, col, 0))
+      : null;
+
+    if (f.name.startsWith("positional_")) {
+      const idx = parseInt(f.name.slice("positional_".length), 10);
+      while (positional.length <= idx) positional.push(null);
+      positional[idx] = val;
+    } else if (f.name.startsWith("named_")) {
+      const name = f.name.slice("named_".length);
+      named.set(name, val);
+    } else {
+      // Try numeric field name (old format)
+      const metadata = f.metadata;
+      const isNamed = metadata?.get?.("vgi_arg") === "named";
+      if (isNamed) {
+        named.set(f.name, val);
+      } else {
+        const idx = parseInt(f.name, 10);
+        if (!isNaN(idx)) {
+          while (positional.length <= idx) positional.push(null);
+          positional[idx] = val;
+        }
+      }
+    }
+  }
+
+  return new Arguments(positional, named, sch);
+}

package/src/protocol/serializers/bind.ts

@@ -0,0 +1,212 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// BindRequest / BindResponse wire serialization. Schemas mirror Python's
+// ArrowSerializableDataclass field declaration order so the format is
+// positional-compatible with the Python reader.
+
+import { type VgiSchema, schema, type VgiField, field, type VgiBatch, type VgiDataType, utf8, binary, bool, list, struct } from "../../arrow/index.js";
+import { Arguments } from "../../arguments/arguments.js";
+import { FunctionType } from "../../types.js";
+import type { BindRequest, BindResponse, CopyFromContext, CopyToContext } from "../types.js";
+import {
+  serializeSchema,
+  deserializeSchema,
+  serializeBatch,
+  deserializeBatch,
+} from "../../util/arrow/index.js";
+import { toUint8Array, buildSingleRowBatch } from "./shared.js";
+import { serializeArguments, deserializeArguments } from "./arguments.js";
+
+const BIND_REQUEST_SCHEMA = schema([
+  field("function_name", utf8(), false),
+  field("arguments", binary(), false),
+  field("function_type", utf8(), false),
+  field("input_schema", binary(), true),
+  field("settings", binary(), true),
+  field("secrets", binary(), true),
+  field("attach_opaque_data", binary(), true),
+  field("transaction_opaque_data", binary(), true),
+  field("resolved_secrets_provided", bool(), false),
+  // Time travel AT clause (additive, nullable, name-keyed -> wire-compatible).
+  // Both null when the scan has no AT clause. See BindRequest.at_unit.
+  field("at_unit", utf8(), true),
+  field("at_value", utf8(), true),
+]);
+
+// COPY ... FROM context — a nullable nested struct<format, file_path,
+// expected_schema>. Byte-for-byte the shape the C++ extension builds in
+// vgi_rpc_types.cpp (BuildBindRequest's copy_from branch) and the Python
+// BindRequest.copy_from field. Only appended to the serialized batch when the
+// bind actually opens a COPY scan, so ordinary scans keep the legacy wire shape.
+const COPY_FROM_STRUCT_TYPE = struct([
+  field("format", utf8(), false),
+  field("file_path", utf8(), false),
+  field("expected_schema", binary(), false),
+]);
+const COPY_FROM_FIELD = field("copy_from", COPY_FROM_STRUCT_TYPE, true);
+
+// COPY ... TO context — a nullable nested struct<format, file_path>.
+// Byte-for-byte the shape the C++ extension builds in vgi_rpc_types.cpp
+// (BuildBindRequest's copy_to branch) and the Python BindRequest.copy_to field.
+// Only appended to the serialized batch when the bind actually opens a COPY TO
+// sink, so ordinary scans keep the legacy wire shape.
+const COPY_TO_STRUCT_TYPE = struct([
+  field("format", utf8(), false),
+  field("file_path", utf8(), false),
+]);
+const COPY_TO_FIELD = field("copy_to", COPY_TO_STRUCT_TYPE, true);
+
+const BIND_RESPONSE_SCHEMA = schema([
+  field("output_schema", binary(), false),
+  field("opaque_data", binary(), true),
+  field("lookup_secret_types", list(field("item", utf8(), true)), false),
+  field("lookup_scopes", list(field("item", utf8(), true)), false),
+  field("lookup_names", list(field("item", utf8(), true)), false),
+]);
+
+export function serializeBindRequest(req: BindRequest): VgiBatch {
+  const row: Record<string, any> = {
+    function_name: req.function_name,
+    arguments: serializeArguments(req.arguments),
+    function_type: req.function_type,
+    input_schema: req.input_schema ? serializeSchema(req.input_schema) : null,
+    settings: req.settings ? serializeBatch(req.settings) : null,
+    secrets: req.secrets ? serializeBatch(req.secrets) : null,
+    attach_opaque_data: req.attach_opaque_data ?? null,
+    transaction_opaque_data: req.transaction_opaque_data ?? null,
+    resolved_secrets_provided: req.resolved_secrets_provided ?? false,
+    at_unit: req.at_unit ?? null,
+    at_value: req.at_value ?? null,
+  };
+  // Append the copy_from / copy_to struct columns only for COPY scans/sinks, so
+  // non-COPY binds serialize to the exact legacy shape (fields matched by name
+  // on the reader). At most one is present in practice, but both are handled
+  // generically so the wire stays additive either way.
+  const extraFields: VgiField[] = [];
+  if (req.copy_from) {
+    extraFields.push(COPY_FROM_FIELD);
+    row.copy_from = {
+      format: req.copy_from.format,
+      file_path: req.copy_from.file_path,
+      expected_schema: serializeSchema(req.copy_from.expected_schema),
+    };
+  }
+  if (req.copy_to) {
+    extraFields.push(COPY_TO_FIELD);
+    row.copy_to = {
+      format: req.copy_to.format,
+      file_path: req.copy_to.file_path,
+    };
+  }
+  if (extraFields.length > 0) {
+    const schemaWithCopy = schema([...BIND_REQUEST_SCHEMA.fields, ...extraFields]);
+    return buildSingleRowBatch(schemaWithCopy, row);
+  }
+  return buildSingleRowBatch(BIND_REQUEST_SCHEMA, row);
+}
+
+function parseCopyFromContext(raw: any): CopyFromContext | null {
+  // The struct column decodes to a plain { format, file_path, expected_schema }
+  // object via the codec/canonical path (expected_schema is binary -> Uint8Array).
+  if (raw == null) return null;
+  const format = raw.format;
+  const filePath = raw.file_path;
+  const schemaBytes = raw.expected_schema;
+  if (format == null || filePath == null || schemaBytes == null) return null;
+  return {
+    format: String(format),
+    file_path: String(filePath),
+    expected_schema: deserializeSchema(toUint8Array(schemaBytes)),
+  };
+}
+
+function parseCopyToContext(raw: any): CopyToContext | null {
+  // The struct column decodes to a plain { format, file_path } object via the
+  // codec/canonical path.
+  if (raw == null) return null;
+  const format = raw.format;
+  const filePath = raw.file_path;
+  if (format == null || filePath == null) return null;
+  return { format: String(format), file_path: String(filePath) };
+}
+
+export function deserializeBindRequest(
+  params: Record<string, any>
+): BindRequest {
+  // params come from the RPC layer - already extracted from a single-row batch
+  // arguments may be null/undefined when DuckDB sends empty args
+  const args = params.arguments
+    ? deserializeArguments(toUint8Array(params.arguments))
+    : new Arguments();
+
+  // function_type might be a string directly or enum name
+  let functionType: FunctionType;
+  const ftStr = String(params.function_type);
+  if (ftStr === "scalar" || ftStr === "SCALAR") {
+    functionType = FunctionType.SCALAR;
+  } else if (ftStr === "table" || ftStr === "TABLE") {
+    functionType = FunctionType.TABLE;
+  } else if (ftStr === "aggregate" || ftStr === "AGGREGATE") {
+    functionType = FunctionType.AGGREGATE;
+  } else {
+    functionType = ftStr as FunctionType;
+  }
+
+  return {
+    function_name: params.function_name,
+    arguments: args,
+    function_type: functionType,
+    input_schema: params.input_schema
+      ? deserializeSchema(toUint8Array(params.input_schema))
+      : null,
+    settings: params.settings
+      ? deserializeBatch(toUint8Array(params.settings))
+      : null,
+    secrets: params.secrets
+      ? deserializeBatch(toUint8Array(params.secrets))
+      : null,
+    attach_opaque_data: params.attach_opaque_data ? toUint8Array(params.attach_opaque_data) : null,
+    transaction_opaque_data: params.transaction_opaque_data
+      ? toUint8Array(params.transaction_opaque_data)
+      : null,
+    resolved_secrets_provided: params.resolved_secrets_provided ?? false,
+    // Empty string -> null (matches the C++ BuildBindRequest convention).
+    at_unit: params.at_unit ? String(params.at_unit) : null,
+    at_value: params.at_value ? String(params.at_value) : null,
+    // COPY ... FROM context — absent for ordinary scans (params.copy_from
+    // undefined -> null). The struct column decodes to a plain object.
+    copy_from: parseCopyFromContext(params.copy_from),
+    // COPY ... TO context — absent for ordinary scans / COPY FROM.
+    copy_to: parseCopyToContext(params.copy_to),
+  };
+}
+
+export function serializeBindResponse(
+  resp: BindResponse
+): Record<string, any> {
+  return {
+    output_schema: serializeSchema(resp.output_schema),
+    opaque_data: resp.opaque_data ?? null,
+    lookup_secret_types: resp.lookup_secret_types ?? [],
+    lookup_scopes: resp.lookup_scopes ?? [],
+    lookup_names: resp.lookup_names ?? [],
+  };
+}
+
+export function deserializeBindResponse(
+  params: Record<string, any>
+): BindResponse {
+  const toStrArray = (val: any): string[] => {
+    if (!val) return [];
+    const arr = Array.isArray(val) ? val : [...val];
+    return arr.filter((v: any) => v != null).map(String);
+  };
+  return {
+    output_schema: deserializeSchema(toUint8Array(params.output_schema)),
+    opaque_data: params.opaque_data ? toUint8Array(params.opaque_data) : null,
+    lookup_secret_types: toStrArray(params.lookup_secret_types),
+    lookup_scopes: toStrArray(params.lookup_scopes),
+    lookup_names: toStrArray(params.lookup_names),
+  };
+}
+
+export { BIND_REQUEST_SCHEMA, BIND_RESPONSE_SCHEMA };

package/src/protocol/serializers/cardinality.ts

@@ -0,0 +1,45 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// TableFunctionCardinalityRequest / TableCardinality wire serialization.
+
+import { type VgiSchema, schema, type VgiField, field, type VgiDataType, binary, int64 } from "../../arrow/index.js";
+import type { TableFunctionCardinalityRequest, TableCardinality } from "../types.js";
+import { deserializeBatch, batchToScalarDict } from "../../util/arrow/index.js";
+import { toUint8Array } from "./shared.js";
+import { deserializeBindRequest } from "./bind.js";
+
+const TABLE_CARDINALITY_SCHEMA = schema([
+  field("estimate", int64(), true),
+  field("max", int64(), true),
+]);
+
+const TABLE_FUNCTION_CARDINALITY_REQUEST_SCHEMA = schema([
+  field("bind_call", binary(), false),
+  field("bind_opaque_data", binary(), true),
+]);
+
+export function deserializeCardinalityRequest(
+  params: Record<string, any>
+): TableFunctionCardinalityRequest {
+  const bindCallBytes = toUint8Array(params.bind_call);
+  const bindCallBatch = deserializeBatch(bindCallBytes);
+  const bindParams = batchToScalarDict(bindCallBatch);
+  const bindCall = deserializeBindRequest(bindParams);
+
+  return {
+    bind_call: bindCall,
+    bind_opaque_data: params.bind_opaque_data
+      ? toUint8Array(params.bind_opaque_data)
+      : null,
+  };
+}
+
+export function serializeTableCardinality(
+  card: TableCardinality
+): Record<string, any> {
+  return {
+    estimate: card.estimate,
+    max: card.max,
+  };
+}
+
+export { TABLE_CARDINALITY_SCHEMA, TABLE_FUNCTION_CARDINALITY_REQUEST_SCHEMA };