@query-farm/vgi 0.6.0

package/dist/metadata/resolve.d.ts

@@ -0,0 +1,3 @@
+import type { VgiFunction } from "../functions/types.js";
+import { type ResolvedMetadata } from "./types.js";
+export declare function resolveMetadata(func: VgiFunction): ResolvedMetadata;

package/dist/metadata/serialize.d.ts

@@ -0,0 +1,12 @@
+import { type VgiBatch } from "../arrow/index.js";
+import type { ResolvedMetadata } from "./types.js";
+declare const METADATA_SCHEMA: import("../index.core.js").VgiSchema;
+export { METADATA_SCHEMA };
+/**
+ * Serialize multiple ResolvedMetadata to a single Arrow RecordBatch.
+ */
+export declare function metadatasToArrow(metadatas: ResolvedMetadata[]): VgiBatch;
+/**
+ * Deserialize Arrow RecordBatch to ResolvedMetadata array.
+ */
+export declare function arrowToMetadatas(batch: VgiBatch): ResolvedMetadata[];

package/dist/metadata/types.d.ts

@@ -0,0 +1,47 @@
+import { FunctionStability, NullHandling, OrderPreservation, OrderDependence, DistinctDependence } from "../types.js";
+export declare enum CatalogFunctionType {
+    SCALAR = "SCALAR",
+    TABLE = "TABLE",
+    TABLE_BUFFERING = "TABLE_BUFFERING",
+    AGGREGATE = "AGGREGATE"
+}
+export interface ParameterInfo {
+    name: string;
+    position: number | null;
+    positionName: string | null;
+    typeName: string | null;
+    description: string;
+    required: boolean;
+    default: string | null;
+    constraints: string | null;
+    isTableInput: boolean;
+    isVarargs: boolean;
+    isConst: boolean;
+}
+export interface FunctionExample {
+    sql: string;
+    description: string;
+    expectedOutput: string | null;
+}
+export interface ResolvedMetadata {
+    name: string;
+    className: string;
+    functionType: CatalogFunctionType;
+    description: string;
+    examples: FunctionExample[];
+    categories: string[];
+    tags: Record<string, string>;
+    parameters: ParameterInfo[];
+    stability: FunctionStability;
+    nullHandling: NullHandling;
+    requiredSettings: string[];
+    requiredSecrets: string[];
+    projectionPushdown: boolean;
+    filterPushdown: boolean;
+    samplingPushdown: boolean;
+    supportedExpressionFilters: string[];
+    preservesOrder: OrderPreservation;
+    maxWorkers: number | null;
+    orderDependent: OrderDependence;
+    distinctDependent: DistinctDependence;
+}

package/dist/protocol/dispatch.d.ts

@@ -0,0 +1,23 @@
+import { Protocol } from "@query-farm/vgi-rpc";
+import type { FunctionRegistry } from "../functions/registry.js";
+import type { CatalogInterface } from "../catalog/interface.js";
+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
+     * transports) attach_opaque_data / transaction_opaque_data pass through
+     * unsealed — OS process ownership already enforces identity there.
+     */
+    signingKey?: Uint8Array;
+}
+export declare function buildVgiProtocol(config: ProtocolConfig): Protocol;

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

@@ -0,0 +1,3 @@
+import { Protocol } from "@query-farm/vgi-rpc";
+import type { FunctionRegistry } from "../../functions/registry.js";
+export declare function registerAggregateMethods(protocol: Protocol, registry: FunctionRegistry): void;

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

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

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

@@ -0,0 +1,3 @@
+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;

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

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

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

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

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

@@ -0,0 +1,70 @@
+import { type VgiSchema } from "../../../arrow/index.js";
+import { Protocol, type AuthContext, type CallContext } from "@query-farm/vgi-rpc";
+import type { CatalogInterface } from "../../../catalog/interface.js";
+export type GetCatalog = () => CatalogInterface;
+/**
+ * Mint and seal a catalog_attach value: prepend a fresh framework UUID
+ * (uuid(16) || catalog_bytes), then seal. Storage shards on the UUID — stable
+ * across re-seals and globally unique, unlike the random-nonce ciphertext or
+ * the (possibly non-unique) catalog bytes. openAttach strips the UUID back off
+ * so the catalog only ever sees its own bytes. Mirrors vgi-python/-go.
+ */
+export declare function sealAttach(plaintext: Uint8Array, auth: AuthContext | undefined, signingKey: Uint8Array | undefined): Promise<Uint8Array>;
+/**
+ * Open an attach envelope returning the FULL framework plaintext
+ * uuid(16) || catalog_bytes (not stripped). Storage shards on the leading UUID.
+ */
+export declare function openAttachFull(envelope: Uint8Array, auth: AuthContext | undefined, signingKey: Uint8Array | undefined): Promise<Uint8Array>;
+/**
+ * Open an attach_opaque_data envelope, returning the catalog's own bytes — the
+ * framework UUID prefix is stripped. This is what catalog/function bodies see;
+ * storage routing uses openAttachFull / deriveShardKey to reach the UUID.
+ */
+export declare function openAttach(envelope: Uint8Array, auth: AuthContext | undefined, signingKey: Uint8Array | undefined): Promise<Uint8Array>;
+/**
+ * deriveShardKey returns the Cloudflare-DO routing key for an attach:
+ * "att-" + hex(the 16-byte framework UUID at the head of the unwrapped attach).
+ * One DO per logical ATTACH. Throws if the uuid is not 16 bytes (the storage
+ * path is always bound to a logical ATTACH).
+ */
+export declare function deriveShardKey(attachUuid: Uint8Array): string;
+/**
+ * shardKeyForAttach unwraps the sealed attach and derives its shard key. An
+ * empty/absent attach yields "" (non-sharding backends ignore the key; the
+ * CfDo backend rejects an empty key server-side, the "must not happen" case).
+ */
+export declare function shardKeyForAttach(sealed: Uint8Array | undefined, auth: AuthContext | undefined, signingKey: Uint8Array | undefined): Promise<string>;
+/**
+ * Seal a plaintext transaction value (catalog_transaction_begin output), bound
+ * to the caller's identity and the parent attach envelope it was minted under.
+ */
+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;
+export declare function makeGetCatalog(catalog: CatalogInterface | undefined): GetCatalog;
+/**
+ * Decode the `options` field of a catalog_attach request into a plain
+ * {name: value} dict. The wire field is either null (no options) or an
+ * IPC-serialized RecordBatch of typed columns — one column per option,
+ * one row with the value. Returns `{}` for null / empty input.
+ */
+export declare function decodeOptionsBatch(bytes: any): Record<string, unknown>;
+export declare const emptyResultSchema: VgiSchema;
+export declare const attachOpaqueDataParam: VgiSchema;
+export declare const attachOpaqueDataTxnParams: VgiSchema;
+export declare const attachOpaqueDataNameTxnParams: VgiSchema;
+export declare const attachOpaqueDataSchemaNameTxnParams: VgiSchema;
+export declare const schemaNameIgnoreNotFoundTxnParams: VgiSchema;
+export declare const schemaNameCommentParams: VgiSchema;
+export declare const schemaNameRenameParams: VgiSchema;
+export declare const columnOpParams: VgiSchema;

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

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

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

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

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

@@ -0,0 +1,8 @@
+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;
+}
+export declare function registerFunctionMethods(protocol: Protocol, config: FunctionHandlerConfig): void;

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

@@ -0,0 +1,31 @@
+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;
+/**
+ * Unwrap a "request" Binary column: deserialize the inner Arrow IPC batch
+ * and return flat columns as a dict (row 0).
+ */
+export declare function unwrapRequest(requestBytes: any): Record<string, any>;
+/**
+ * Wrap a dict of values into a single "result" Binary column.
+ * Builds a 1-row batch from the values using the given schema,
+ * serializes it to IPC bytes, and returns { result: bytes }.
+ */
+export declare function wrapResult(values: Record<string, any>, innerSchema: VgiSchema | import("../../arrow/index.js").VgiSchema): {
+    result: Uint8Array;
+};
+export declare function overloadContext(req: {
+    function_name: string;
+    arguments: any;
+    input_schema: any;
+    function_type: any;
+}): 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/handlers/table-buffering.d.ts

@@ -0,0 +1,3 @@
+import { Protocol } from "@query-farm/vgi-rpc";
+import type { FunctionRegistry } from "../../functions/registry.js";
+export declare function registerTableBufferingMethods(protocol: Protocol, registry: FunctionRegistry, signingKey?: Uint8Array): void;

package/dist/protocol/serialize.d.ts

@@ -0,0 +1,4 @@
+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/dist/protocol/serializers/arguments.d.ts

@@ -0,0 +1,3 @@
+import { Arguments } from "../../arguments/arguments.js";
+export declare function serializeArguments(args: Arguments): Uint8Array;
+export declare function deserializeArguments(bytes: Uint8Array): Arguments;

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

@@ -0,0 +1,9 @@
+import { type VgiSchema, type VgiBatch } from "../../arrow/index.js";
+import type { BindRequest, BindResponse } from "../types.js";
+declare const BIND_REQUEST_SCHEMA: VgiSchema;
+declare const BIND_RESPONSE_SCHEMA: VgiSchema;
+export declare function serializeBindRequest(req: BindRequest): VgiBatch;
+export declare function deserializeBindRequest(params: Record<string, any>): BindRequest;
+export declare function serializeBindResponse(resp: BindResponse): Record<string, any>;
+export declare function deserializeBindResponse(params: Record<string, any>): BindResponse;
+export { BIND_REQUEST_SCHEMA, BIND_RESPONSE_SCHEMA };

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

@@ -0,0 +1,7 @@
+import { type VgiSchema } from "../../arrow/index.js";
+import type { TableFunctionCardinalityRequest, TableCardinality } from "../types.js";
+declare const TABLE_CARDINALITY_SCHEMA: VgiSchema;
+declare const TABLE_FUNCTION_CARDINALITY_REQUEST_SCHEMA: VgiSchema;
+export declare function deserializeCardinalityRequest(params: Record<string, any>): TableFunctionCardinalityRequest;
+export declare function serializeTableCardinality(card: TableCardinality): Record<string, any>;
+export { TABLE_CARDINALITY_SCHEMA, TABLE_FUNCTION_CARDINALITY_REQUEST_SCHEMA };

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

@@ -0,0 +1,9 @@
+import { type VgiBatch } from "../../arrow/index.js";
+import { type InitRequest, type GlobalInitResponse } from "../types.js";
+declare const INIT_REQUEST_SCHEMA: import("../../index.core.js").VgiSchema;
+declare const GLOBAL_INIT_RESPONSE_SCHEMA: import("../../index.core.js").VgiSchema;
+export declare function serializeInitRequest(req: InitRequest): VgiBatch;
+export declare function deserializeInitRequest(params: Record<string, any>): InitRequest;
+export declare function serializeGlobalInitResponse(resp: GlobalInitResponse): Record<string, any>;
+export declare function deserializeGlobalInitResponse(params: Record<string, any>): GlobalInitResponse;
+export { INIT_REQUEST_SCHEMA, GLOBAL_INIT_RESPONSE_SCHEMA };

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

@@ -0,0 +1,12 @@
+import { type VgiSchema, type VgiBatch } from "../../arrow/index.js";
+/**
+ * Coerce a wire value (string / Uint8Array / Buffer / etc.) to a Uint8Array.
+ * Throws when the input is non-null but produces zero bytes — that signals a
+ * truly unsupported shape, distinct from a legitimate empty Uint8Array.
+ */
+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.
+ */
+export declare function buildSingleRowBatch(schema: VgiSchema, values: Record<string, any>): VgiBatch;

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

@@ -0,0 +1,23 @@
+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. */
+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;
+/**
+ * Serialize userState to Arrow IPC bytes.
+ * Infers schema from the JS object at runtime. Arrow IPC is self-describing,
+ * so deserialization doesn't need the schema ahead of time.
+ *
+ * For an empty object `{}`, we emit a 0-row batch with empty schema —
+ * `deserializeUserState` recognizes that shape and returns `{}` rather than
+ * `null`. (`null` is reserved for "no userState declared at all".)
+ */
+export declare function serializeUserState(userState: any): Uint8Array | null;
+/**
+ * Deserialize userState from Arrow IPC bytes.
+ * 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. */
+export declare const arrowStateSerializer: StateSerializer;

package/dist/protocol/types.d.ts

@@ -0,0 +1,129 @@
+import type { VgiSchema, VgiBatch } from "../arrow/index.js";
+import type { Arguments } from "../arguments/arguments.js";
+import { FunctionType, TableInOutPhase, type TableCardinality } from "../types.js";
+/**
+ * Context for a `COPY ... FROM` read, threaded onto {@link BindRequest}.
+ *
+ * Present only when the bind/init opens a COPY-FROM scan (`null`/absent
+ * otherwise — set by the VGI extension's `copy_from_bind`). `InitRequest`
+ * embeds the same `BindRequest` as `bind_call`, so process()/init also reach it
+ * via `initCall.bind_call.copy_from`. The handler's options arrive through the
+ * normal `BindRequest.arguments` (built from the COPY options), so they are not
+ * duplicated here. Mirrors vgi-python's `protocol.CopyFromContext`.
+ */
+export interface CopyFromContext {
+    /** The `FORMAT` name resolved at COPY bind time. */
+    format: string;
+    /** The source path from the `COPY ... FROM 'path'` statement. */
+    file_path: string;
+    /**
+     * The COPY target's column schema (name + type, in target order). The worker
+     * must bind its output to, and emit columns whose types match, this schema
+     * exactly — DuckDB inserts no cast between the scan and the INSERT. Holds the
+     * parsed Arrow Schema (the wire field is binary; deserialized here).
+     */
+    expected_schema: VgiSchema;
+}
+/**
+ * Context for a `COPY ... TO` write, threaded onto {@link BindRequest}.
+ *
+ * Present only when the bind/init opens a COPY-TO sink (`null`/absent
+ * otherwise — set by the VGI extension's `copy_to_bind`). `InitRequest`
+ * embeds the same `BindRequest` as `bind_call`, so process()/combine() also
+ * reach it via `initCall.bind_call.copy_to`. The handler's options arrive
+ * through the normal `BindRequest.arguments`; the **source** columns ride the
+ * existing `BindRequest.input_schema` (so they are not duplicated here).
+ * Mirrors vgi-python's `protocol.CopyToContext`.
+ */
+export interface CopyToContext {
+    /** The `FORMAT` name resolved at COPY bind time. */
+    format: string;
+    /** The destination path from the `COPY ... TO 'path'` statement. */
+    file_path: string;
+}
+export interface BindRequest {
+    function_name: string;
+    arguments: Arguments;
+    function_type: FunctionType;
+    input_schema: VgiSchema | null;
+    settings: VgiBatch | null;
+    secrets: VgiBatch | null;
+    attach_opaque_data: Uint8Array | null;
+    transaction_opaque_data: Uint8Array | null;
+    resolved_secrets_provided: boolean;
+    /**
+     * COPY ... FROM context — `null`/absent unless this bind/init opens a
+     * COPY-FROM scan. Additive + name-keyed, so ordinary scans (which omit it on
+     * the wire) deserialize to `null`. Mirrors vgi-python's `BindRequest.copy_from`.
+     */
+    copy_from?: CopyFromContext | null;
+    /**
+     * COPY ... TO context — `null`/absent unless this bind/init opens a COPY-TO
+     * sink. Additive + name-keyed, same wire-safe rationale as `copy_from`.
+     * Mirrors vgi-python's `BindRequest.copy_to`.
+     */
+    copy_to?: CopyToContext | null;
+    /**
+     * Time travel: the AT (TIMESTAMP|VERSION ...) clause for this scan, threaded
+     * from DuckDB's per-reference bind. Both `null` when the scan has no AT clause.
+     * For inline-bound (function-backed) tables the actual on_bind RPC runs once at
+     * attach with no AT, so the per-scan AT is carried on the bind request embedded
+     * in each InitRequest — read it at init via `init_call.bind_call.at_unit` (or
+     * `TableProcessParams.atUnit`). Mirrors vgi-python's `BindRequest.at_unit`.
+     */
+    at_unit?: string | null;
+    at_value?: string | null;
+}
+export interface BindResponse {
+    output_schema: VgiSchema;
+    opaque_data: Uint8Array | null;
+    lookup_secret_types?: string[];
+    lookup_scopes?: string[];
+    lookup_names?: string[];
+}
+export interface InitRequest {
+    bind_call: BindRequest;
+    output_schema: VgiSchema;
+    bind_opaque_data: Uint8Array | null;
+    projection_ids: number[] | null;
+    pushdown_filters: VgiBatch | null;
+    /**
+     * Join-key value batches, one per join-keys column. Keyed by the column
+     * name inside each batch's schema. Populated when DuckDB promotes
+     * IN/OR lists or join predicates to batched join-keys pushdowns.
+     */
+    join_keys: VgiBatch[];
+    phase: TableInOutPhase | null;
+    /**
+     * Buffered-table finalize stream: which finalize_state_id this stream
+     * serves. Set when phase=TABLE_BUFFERING_FINALIZE; null otherwise. Opaque
+     * bytes the worker's combine() chose.
+     */
+    finalize_state_id: Uint8Array | null;
+    execution_id: Uint8Array | null;
+    init_opaque_data: Uint8Array | null;
+    order_by_column_name: string | null;
+    order_by_direction: OrderByDirection | null;
+    order_by_null_order: OrderByNullOrder | null;
+    order_by_limit: bigint | null;
+    tablesample_percentage: number | null;
+    tablesample_seed: bigint | null;
+}
+export declare enum OrderByDirection {
+    ASC = "ASC",
+    DESC = "DESC"
+}
+export declare enum OrderByNullOrder {
+    NULLS_FIRST = "NULLS_FIRST",
+    NULLS_LAST = "NULLS_LAST"
+}
+export interface GlobalInitResponse {
+    max_workers: number;
+    execution_id: Uint8Array;
+    opaque_data: Uint8Array | null;
+}
+export interface TableFunctionCardinalityRequest {
+    bind_call: BindRequest;
+    bind_opaque_data: Uint8Array | null;
+}
+export { TableCardinality };

package/dist/secrets/helpers.d.ts

@@ -0,0 +1,15 @@
+export type SecretFields = Record<string, any>;
+export type SecretsDict = Record<string, SecretFields>;
+/** The DuckDB secret type of the named secret (its serialized `type` field). */
+export declare function secretType(secrets: SecretsDict, name: string): string | undefined;
+/** Every resolved secret whose serialized `type` field matches `type`. */
+export declare function secretsOfType(secrets: SecretsDict, type: string): SecretFields[];
+/**
+ * The secret whose `scope` is the longest prefix of `path`. The connector
+ * serializes each secret's scope as a newline-joined list of prefixes; a secret
+ * with no (or empty) scope matches as a last-resort fallback. Returns undefined
+ * only when there are no candidate secrets.
+ */
+export declare function secretForScope(secrets: SecretsDict, path: string): SecretFields | undefined;
+/** Like {@link secretForScope} but only over secrets of `type`. */
+export declare function secretForScopeOfType(secrets: SecretsDict, path: string, type: string): SecretFields | undefined;

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+export declare enum FunctionType {
+    SCALAR = "scalar",
+    TABLE = "table",
+    AGGREGATE = "aggregate"
+}
+export declare enum FunctionStability {
+    CONSISTENT = "CONSISTENT",
+    VOLATILE = "VOLATILE",
+    CONSISTENT_WITHIN_QUERY = "CONSISTENT_WITHIN_QUERY"
+}
+export declare enum NullHandling {
+    DEFAULT = "DEFAULT",
+    SPECIAL = "SPECIAL"
+}
+export declare enum OrderPreservation {
+    /** Output rows are in same order as input rows (DuckDB INSERTION_ORDER). */
+    PRESERVES_ORDER = "PRESERVES_ORDER",
+    /** Output order is undefined; may be reordered (DuckDB NO_ORDER). */
+    NO_ORDER_GUARANTEE = "NO_ORDER_GUARANTEE",
+    /** Output is in a fixed mandatory order; DuckDB serialises the pipeline
+     *  (single worker) to preserve it (DuckDB FIXED_ORDER). */
+    FIXED_ORDER = "FIXED_ORDER"
+}
+export declare enum OrderDependence {
+    ORDER_DEPENDENT = "ORDER_DEPENDENT",
+    NOT_ORDER_DEPENDENT = "NOT_ORDER_DEPENDENT"
+}
+export declare enum DistinctDependence {
+    DISTINCT_DEPENDENT = "DISTINCT_DEPENDENT",
+    NOT_DISTINCT_DEPENDENT = "NOT_DISTINCT_DEPENDENT"
+}
+export declare enum TableInOutPhase {
+    INPUT = "INPUT",
+    FINALIZE = "FINALIZE",
+    TABLE_BUFFERING = "TABLE_BUFFERING",
+    TABLE_BUFFERING_FINALIZE = "TABLE_BUFFERING_FINALIZE"
+}
+export declare const VGI_ARG_KEY = "vgi_arg";
+export declare const VGI_ARG_NAMED = "named";
+export declare const VGI_TYPE_KEY = "vgi_type";
+export declare const VGI_TYPE_TABLE = "table";
+export declare const VGI_TYPE_ANY = "any";
+export declare const VGI_VARARGS_KEY = "vgi_varargs";
+export declare const VGI_VARARGS_TRUE = "true";
+export declare const VGI_CONST_KEY = "vgi_const";
+export declare const VGI_CONST_TRUE = "true";
+export declare const VGI_DOC_KEY = "vgi_doc";
+export interface TableCardinality {
+    estimate: number | null;
+    max: number | null;
+}
+export declare const DEFAULT_MAX_WORKERS = 99999;

package/dist/util/arrow/index.d.ts

@@ -0,0 +1 @@
+export { emptyBatch, batchFromRows, batchFromColumns, iterRows, batchToScalarDict, batchToSecretDict, safeNumber, decodeDictValue, filterBatch, projectSchema, projectBatch, serializeSchema, deserializeSchema, serializeBatch, deserializeBatch, } from "../../arrow/index.js";

package/dist/util/bytes.d.ts

@@ -0,0 +1,2 @@
+/** Convert any binary-ish value to a Uint8Array. Returns empty array for null/undefined. */
+export declare function toUint8Array(val: any): Uint8Array;

package/dist/util/statistics.d.ts

@@ -0,0 +1,7 @@
+import { type ColumnStatistics } from "../arrow/index.js";
+export type { ColumnStatistics };
+/**
+ * Serialize column statistics to IPC bytes per vgi-python's wire format.
+ * Returns an empty-stats batch when `stats` is empty (matching Python).
+ */
+export declare function serializeColumnStatistics(stats: ColumnStatistics[], _cacheMaxAgeSeconds?: number | null): Uint8Array;

package/dist/worker-cf-entry.d.ts

@@ -0,0 +1,30 @@
+import { type ProtocolConfig } from "./protocol/dispatch.js";
+export interface VgiFetchOptions {
+    /** Wire-protocol config (registry + catalogInterface). */
+    protocol: Omit<ProtocolConfig, "recoverExchangeState">;
+    /** HMAC key for state-token signing. Pass a stable, secret 32-byte key
+     *  (e.g. derived from a Wrangler secret). Required because Workers don't
+     *  preserve in-memory state across requests/instances. */
+    signingKey: Uint8Array;
+    /** State-token TTL in seconds (default 3600). */
+    tokenTtl?: number;
+    /** URL path prefix for VGI requests (default "/vgi"). */
+    prefix?: string;
+    /** Server ID for state-token attribution (default "vgi-cf"). */
+    serverId?: string;
+}
+/**
+ * Build a fetch handler suitable for `export default { fetch }` in a CF
+ * Worker module. The returned handler is async-safe across Workers'
+ * isolate-per-request execution model — all state round-trips through the
+ * signed state token created here.
+ */
+export declare function createVgiFetch(opts: VgiFetchOptions): (req: Request) => Promise<Response>;
+export { defineScalarFunction, defineTableFunction, defineAggregate, defineTableInOutFunction, FunctionRegistry, ReadOnlyCatalogInterface, CompositeCatalogInterface, CatalogInterface, Arguments, FunctionType, serializeAttachOptionSpec, serializeAttachOptionSpecs, serializeColumnStatistics, BindResultSchema, ScanFunctionResultSchema, } from "./index.core.js";
+export type { AttachOptionSpec, ColumnStatistics, CatalogAttachResult, CatalogDescriptor, CatalogInfo, TableInfo, AttachOpaqueData, TransactionOpaqueData, SchemaInfo, VgiFunction, TableProcessParams, } from "./index.core.js";
+export type { ProtocolConfig } from "./protocol/dispatch.js";
+export { TypeId, isNull, isInt, isFloat, isBinary, isUtf8, isBool, isDecimal, isDate, isTime, isTimestamp, isInterval, isList, isStruct, isUnion, isFixedSizeBinary, isFixedSizeList, isMap, isDuration, isDictionary, isBatch, backend, schema, field, nullType, bool, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, float16, float32, float64, utf8, binary, fixedSizeBinary, decimal, decimal128, decimal256, date, dateDay, dateMillisecond, time, timeSecond, timeMillisecond, timeMicrosecond, timeNanosecond, timestamp, duration, interval, list, fixedSizeList, struct, map, dictionary, union, sparseUnion, denseUnion, TimeUnit, DateUnit, IntervalUnit, UnionMode, emptyBatch, batchFromRows, batchFromColumns, columnFromArray, iterRows, batchToScalarDict, batchToSecretDict, safeNumber, decodeDictValue, filterBatch, projectSchema, projectBatch, serializeSchema, deserializeSchema, serializeBatch, deserializeBatch, buildStatisticsBatch, } from "./arrow/index.js";
+export type { VgiTypeId, VgiDataType, VgiField, VgiSchema, VgiColumn, VgiColumnData, VgiBatch, VgiBackendInfo, } from "./arrow/index.js";
+export { arrowStateSerializer, EXCHANGE_STATE_SCHEMA } from "./protocol/state-serializer.js";
+export { OutputCollector, AuthContext } from "@query-farm/vgi-rpc";
+export type { LogMessage } from "@query-farm/vgi-rpc";