@query-farm/vgi 0.28.0 → 0.29.1

package/dist/filter-pushdown/capabilities.d.ts

@@ -0,0 +1,3 @@
+import type { FunctionIdentity } from "./types.js";
+export declare function filterFunctionIdentityKey(identity: FunctionIdentity): string;
+export declare function supportsExtensionFilterFunction(identity: FunctionIdentity): boolean;

package/dist/filter-pushdown/deserialize.d.ts

@@ -1,16 +1,15 @@
-import { type VgiBatch } from "../arrow/index.js";
+import { type VgiBatch, type VgiSchema } from "../arrow/index.js";
 import { PushdownFilters } from "./evaluate.js";
-/**
- * Build a getJoinKeysColumn lookup from an InitRequest's `joinKeys` batches.
- * Each batch typically has a single column whose name is the join-keys column
- * referenced by `spec.keys_column` on a join_keys filter.
- */
-export declare function buildJoinKeysLookup(joinKeyBatches: VgiBatch[]): (columnName: string) => any[] | null;
-/**
- * Deserialize pushdown filters from an Arrow RecordBatch.
- *
- * Wire format:
- * - Column 0: UTF8 — JSON array of filter specs. Field metadata: vgi_filter_version: "1"
- * - Columns 1+: Scalar values referenced by value_ref → column N+1
- */
-export declare function deserializeFilters(batch: VgiBatch, getJoinKeysColumn?: (columnName: string) => any[] | null): PushdownFilters;
+import { type FilterCapabilities } from "./types.js";
+export declare class FilterV2Error extends Error {
+    constructor(message: string);
+}
+export interface DeserializeFilterOptions extends FilterCapabilities {
+    /** The authoritative, unprojected bind output schema. */
+    outputSchema: VgiSchema;
+    joinKeyBatches?: VgiBatch[];
+}
+export declare function deserializeFilters(batch: VgiBatch, options: DeserializeFilterOptions): PushdownFilters;
+export declare function applyFilterDelta(prior: PushdownFilters, batch: VgiBatch): PushdownFilters;
+/** @deprecated External-set references are positional in v2; pass joinKeyBatches instead. */
+export declare function buildJoinKeysLookup(joinKeyBatches: VgiBatch[]): (columnName: string) => unknown[] | null;

package/dist/filter-pushdown/evaluate.d.ts

@@ -1,51 +1,21 @@
 import { type VgiBatch } from "../arrow/index.js";
-import { type Filter } from "./types.js";
+import { type DeserializeFilterOptions } from "./deserialize.js";
+import { type EvaluationContext, type FilterExpression, type FilterPredicate } from "./types.js";
 export declare class PushdownFilters {
-    readonly filters: Filter[];
-    readonly version: string;
-    constructor(filters: Filter[], version: string);
-    /** Convert filters to a human-readable SQL-like string. */
-    toSql(): string;
-    /** Evaluate filters against a batch, returning a Uint8Array mask (0=fail, 1=pass). */
+    readonly predicates: FilterPredicate[];
+    readonly evaluationContext: EvaluationContext;
+    readonly options: DeserializeFilterOptions;
+    readonly revisions: Map<string, number>;
+    readonly requiredIds: Set<string>;
+    readonly version = "2";
+    constructor(predicates: FilterPredicate[], evaluationContext: EvaluationContext, options: DeserializeFilterOptions, revisions?: Map<string, number>, requiredIds?: Set<string>);
+    get filters(): FilterExpression[];
+    applyDelta(batch: VgiBatch): PushdownFilters;
     evaluate(batch: VgiBatch): Uint8Array;
-    /** Apply filters to a batch, returning only passing rows. */
     apply(batch: VgiBatch): VgiBatch;
-    /**
-     * The set of column names referenced by the pushed-down filters, sorted
-     * ascending. Descends one level into AndFilter children (DuckDB pushes
-     * `col IN (...) AND col>=min` as a single AndFilter), consistent with
-     * `getColumnValues` / `hasFilterForColumn`. Mirrors the cross-language
-     * `filtered_columns` accessor (vgi-python / vgi-go / vgi-rust).
-     */
     filteredColumns(): string[];
-    /**
-     * Whether any pushed-down filter references `columnName`. Mirrors the
-     * cross-language `has_filter_for_column` accessor.
-     */
     hasFilterForColumn(columnName: string): boolean;
-    /**
-     * Discrete values a column could take, from equality (`=`) or `IN` filters.
-     * Useful for partition pruning (resolve the key set up front, fetch only
-     * those keys). Returns null when the predicate is not enumerable — no
-     * filter, a bare range, or an OR with a non-discrete branch.
-     *
-     * Mirrors vgi-python's `PushdownFilters.get_column_values`: descends one
-     * level into an AndFilter (DuckDB pushes `col IN (...) AND col>=min AND
-     * col<=max` as a single AndFilter from a semi-join), and unions OR branches
-     * only when every branch pins the column to discrete values.
-     */
-    getColumnValues(columnName: string): any[] | null;
-    /**
-     * Union of discrete values for `columnName` across all OR branches, iff every
-     * child constrains it to discrete values (`=` or `IN`); otherwise null (the
-     * column could take any value through a non-discrete branch). Returning one
-     * branch's values would be an unsafe subset.
-     */
-    private orDiscreteValues;
-    /**
-     * Collect filters for a column from the top level and direct AND children
-     * (one level of descent, consistent with the Python accessor). Deeply nested
-     * AND/AND is not traversed.
-     */
-    private collectColumnFilters;
+    getColumnValues(columnName: string): unknown[] | null;
+    toSql(): string;
 }
+export declare function expressionToSql(expression: FilterExpression): string;

package/dist/filter-pushdown/index.d.ts

@@ -1,4 +1,4 @@
-export { ComparisonOp, type AndFilter, type ConstantFilter, type ExpressionFilter, type ExprNode, type Filter, type InFilter, type IsNotNullFilter, type IsNullFilter, type OrFilter, type StructFilter, } from "./types.js";
+export { FILTER_ENCODING, FILTER_VERSION, DUCKDB_STANDARD_V1, NO_EVALUATION_CONTEXT, DUCKDB_SESSION_CONTEXT, ComparisonOp, type ArithmeticOp, type EvaluationContext, type Filter, type AndFilter, type ConstantFilter, type ExpressionFilter, type ExprNode, type InFilter, type IsNotNullFilter, type IsNullFilter, type OrFilter, type StructFilter, type FilterExpression, type FilterPredicate, type FilterSet, type FunctionIdentity, type PredicateMode, type PredicateSource, type StandardFilterFunction, } from "./types.js";
 export { PushdownFilters } from "./evaluate.js";
-export { buildJoinKeysLookup, deserializeFilters } from "./deserialize.js";
+export { FilterV2Error, applyFilterDelta, buildJoinKeysLookup, deserializeFilters } from "./deserialize.js";
 export { FilteringOutputCollector, formatPushedFilters, reprPushedFilters, } from "./collector.js";

package/dist/filter-pushdown/types.d.ts

@@ -1,84 +1,136 @@
+import type { VgiBatch, VgiDataType, VgiField } from "../arrow/index.js";
+export declare const FILTER_ENCODING = "vgi.filters.v2";
+export declare const FILTER_VERSION = "2";
+export declare const DUCKDB_STANDARD_V1 = "vgi.duckdb.standard.v1";
+export declare const NO_EVALUATION_CONTEXT = "vgi.none.v1";
+export declare const DUCKDB_SESSION_CONTEXT = "vgi.duckdb.session.v1";
 export declare enum ComparisonOp {
     EQ = "eq",
     NE = "ne",
+    LT = "lt",
+    LE = "le",
     GT = "gt",
     GE = "ge",
-    LT = "lt",
-    LE = "le"
+    DISTINCT_FROM = "distinct_from",
+    NOT_DISTINCT_FROM = "not_distinct_from"
 }
-export interface ConstantFilter {
-    type: "constant";
-    columnName: string;
-    columnIndex: number;
-    op: ComparisonOp;
-    value: any;
+export type ArithmeticOp = "add" | "subtract" | "multiply" | "divide" | "modulo";
+export type PredicateMode = "required" | "advisory";
+export type PredicateSource = "query" | "join" | "top_n" | "split_refinement" | "other";
+export type StandardFilterFunction = "starts_with" | "ends_with" | "contains" | "list_contains";
+export interface FunctionIdentity {
+    namespace: string;
+    name: string;
+    version: number;
 }
-export interface IsNullFilter {
-    type: "is_null";
-    columnName: string;
-    columnIndex: number;
+export interface EvaluationContext {
+    profile: string;
+    timeZone?: string;
+    calendar?: string;
+    defaultCollation?: string;
+    ieeeFloatingPointOps?: boolean;
+    integerDivision?: boolean;
+    providerFingerprint?: string;
 }
-export interface IsNotNullFilter {
-    type: "is_not_null";
-    columnName: string;
+export type FilterExpression = {
+    node: "column_ref";
     columnIndex: number;
-}
-export interface InFilter {
-    type: "in";
     columnName: string;
-    columnIndex: number;
-    values: Set<any>;
-}
-export interface AndFilter {
-    type: "and";
-    columnName: string;
-    columnIndex: number;
-    children: Filter[];
-}
-export interface OrFilter {
-    type: "or";
-    columnName: string;
-    columnIndex: number;
-    children: Filter[];
-}
-export interface StructFilter {
-    type: "struct";
-    columnName: string;
-    columnIndex: number;
-    childIndex: number;
-    childName: string;
-    childFilter: Filter;
-}
-export type Filter = ConstantFilter | IsNullFilter | IsNotNullFilter | InFilter | AndFilter | OrFilter | StructFilter | ExpressionFilter;
-/**
- * Expression-tree filter. The expr is a parsed AST; evaluation matches
- * DuckDB's semantics for the function names the table function advertises in
- * `supportedExpressionFilters` (e.g. list_contains, starts_with, contains,
- * &&/st_intersects_extent for spatial).
- */
-export interface ExpressionFilter {
-    type: "expression";
-    columnName: string;
-    columnIndex: number;
-    expr: ExprNode;
-}
-export type ExprNode = {
-    expr_type: "column_ref";
-    index: number;
+    dataType?: VgiDataType;
 } | {
-    expr_type: "constant";
-    value: any;
+    node: "field_ref";
+    expression: FilterExpression;
+    fieldIndex: number;
+    fieldName: string;
+    dataType: VgiDataType;
 } | {
-    expr_type: "function";
-    function_name: string;
-    children: ExprNode[];
+    node: "literal";
+    valueRef: number;
+    field: VgiField;
+    value: unknown;
 } | {
-    expr_type: "comparison";
+    node: "comparison";
     op: ComparisonOp;
-    left: ExprNode;
-    right: ExprNode;
+    left: FilterExpression;
+    right: FilterExpression;
+} | {
+    node: "and" | "or";
+    children: FilterExpression[];
+} | {
+    node: "not";
+    expression: FilterExpression;
+} | {
+    node: "is_null";
+    expression: FilterExpression;
+    negated: boolean;
+} | {
+    node: "in";
+    expression: FilterExpression;
+    set: FilterSet;
+    negated: boolean;
+} | {
+    node: "cast";
+    expression: FilterExpression;
+    typeRef: number;
+    field: VgiField;
 } | {
-    expr_type: "conjunction";
-    conjunction_type: "and" | "or";
-    children: ExprNode[];
+    node: "arithmetic";
+    op: ArithmeticOp;
+    left: FilterExpression;
+    right: FilterExpression;
+} | {
+    node: "negate";
+    expression: FilterExpression;
+} | {
+    node: "call";
+    function: StandardFilterFunction | FunctionIdentity;
+    arguments: FilterExpression[];
+    options?: Record<string, unknown>;
+} | {
+    node: "runtime_filter";
+    algorithm: FunctionIdentity;
+    input: FilterExpression;
+    artifactRef: number;
+    field: VgiField;
+    artifact: unknown;
+    nullHandling: "pass" | "reject";
+    supported: boolean;
 };
+export type FilterSet = {
+    kind: "literal";
+    valueRef: number;
+    field: VgiField;
+    values: unknown[];
+} | {
+    kind: "external";
+    batchIndex: number;
+    columnIndex: number;
+    columnName: string;
+    values: unknown[];
+    batch: VgiBatch;
+};
+export interface FilterPredicate {
+    id: string;
+    revision: number;
+    mode: PredicateMode;
+    source: PredicateSource;
+    expression: FilterExpression;
+}
+export interface FilterCapabilities {
+    extensionFunctions?: ReadonlyArray<FunctionIdentity>;
+    runtimeAlgorithms?: ReadonlyArray<FunctionIdentity>;
+    evaluationContexts?: ReadonlyArray<{
+        profile: string;
+        providerFingerprint?: string | null;
+    }>;
+}
+export type Filter = FilterExpression;
+export type ExprNode = FilterExpression;
+export type ConstantFilter = FilterExpression;
+export type IsNullFilter = FilterExpression;
+export type IsNotNullFilter = FilterExpression;
+export type InFilter = FilterExpression;
+export type AndFilter = FilterExpression;
+export type OrFilter = FilterExpression;
+export type StructFilter = FilterExpression;
+export type ExpressionFilter = FilterExpression;

package/dist/functions/aggregate.d.ts

@@ -10,6 +10,8 @@ export interface AggregateBindParams<TArgs = Record<string, any>> {
     inputSchema: VgiSchema | null;
     settings: Record<string, any>;
     secrets: Record<string, Record<string, any>>;
+    /** Resolved names aligned with the complete logical argument order. */
+    argumentNames: (string | null)[] | null;
 }
 export interface AggregateUpdateParams<TArgs = Record<string, any>, TState = any> {
     states: Map<bigint, TState>;
@@ -71,6 +73,8 @@ export interface AggregateFunctionConfig<TArgs = Record<string, any>, TState = a
     onBind?: (params: AggregateBindParams<TArgs>) => VgiDataType | Promise<VgiDataType>;
     /** Optional per-arg default values (positional only here). */
     argDefaults?: Record<string, any>;
+    /** Authoritative typed defaults: one row, defaulted parameters only. */
+    parameterDefaultValues?: VgiBatch | null;
     /**
      * Per-argument discovery constraints (choices / ge / le / gt / lt / pattern),
      * keyed by argument name. Surfaced via `vgi_function_arguments()` and enforced

package/dist/functions/registry.d.ts

@@ -6,12 +6,12 @@ export interface OverloadContext {
     inputSchema?: VgiSchema | null;
     isScalar?: boolean;
     /**
-     * Catalog schema that declares the function, from `BindRequest.schema_name`.
+     * Catalog schema that declares the function, from `BindRequest.schema_path`.
      * A worker may register the same name in more than one schema, so the bare
      * name is not a unique key. When set, resolution is scoped to that schema and
      * never falls back to another one; when absent, every schema is searched.
      */
-    schemaName?: string | null;
+    schemaPath?: string[] | null;
     /**
      * Catalog that owns the function, resolved from the bind's
      * `attach_opaque_data`. Two catalogs served by one worker may each declare
@@ -26,14 +26,14 @@ export declare class FunctionRegistry {
     private _byCatalog;
     register(func: VgiFunction): void;
     /**
-     * Record that `func` is declared in `schemaName`, in addition to the flat
+     * Record that `func` is declared in `schemaPath`, in addition to the flat
      * by-name index. Idempotent, and independent of `register()` so a function
      * reachable from several schemas (e.g. a scan function referenced by tables in
      * more than one schema) resolves from any of them.
      */
-    registerInSchema(func: VgiFunction, schemaName: string, catalogName?: string): void;
+    registerInSchema(func: VgiFunction, schemaPath: string[], catalogName?: string): void;
     /** Schemas that declare `functionName`, sorted — for error messages. */
-    schemasFor(functionName: string): string[];
+    schemasFor(functionName: string): string[][];
     get(name: string, context?: OverloadContext): VgiFunction;
     /**
      * Pick one function from an already-scoped candidate list, by argument shape

package/dist/functions/scalar.d.ts

@@ -1,6 +1,6 @@
 import { type VgiSchema, type VgiBatch, type VgiDataType, type ValueFor, type Repr } from "../arrow/index.js";
 import type { AuthContext } from "@query-farm/vgi-rpc";
-import { FunctionStability, NullHandling } from "../types.js";
+import { FunctionStability, NullHandling, ArgumentMonotonicity } from "../types.js";
 import type { BindRequest } from "../protocol/types.js";
 import type { VgiFunction, FunctionExample } from "./types.js";
 import { type CacheControl } from "../cache-control.js";
@@ -15,6 +15,8 @@ export interface ScalarBindParameters {
     secrets: Record<string, Record<string, any>>;
     /** Original bind request — exposes attach_opaque_data, transaction_opaque_data, function_type, etc. */
     bindCall: BindRequest;
+    /** Resolved names aligned with the complete logical argument order. */
+    argumentNames: (string | null)[] | null;
 }
 /** Ordered parameter definition for scalar functions. */
 export interface ScalarParameterDef {
@@ -103,9 +105,12 @@ export interface ScalarFunctionConfig<P extends Record<string, VgiDataType> = Re
     }) => ScalarComputeResult<NoInfer<R>, NoInfer<M>>;
     stability?: FunctionStability;
     nullHandling?: NullHandling;
+    /** One scalar monotonicity claim per ordered parameter declaration. */
+    argumentMonotonicity?: ArgumentMonotonicity[] | null;
     examples?: FunctionExample[];
     categories?: string[];
     tags?: Record<string, string>;
+    parameterDefaultValues?: VgiBatch | null;
     maxWorkers?: number;
     requiredSettings?: string[];
     requiredSecrets?: string[];

package/dist/functions/table-buffering.d.ts

@@ -3,6 +3,7 @@ import type { OutputCollector } from "@query-farm/vgi-rpc";
 import type { BindRequest, InitRequest, GlobalInitResponse } from "../protocol/types.js";
 import type { TableCardinality } from "../types.js";
 import type { VgiFunction, FunctionExample } from "./types.js";
+import type { ArgumentConstraints } from "../arguments/argument-spec.js";
 import { FunctionStability } from "../types.js";
 import { BoundStorage } from "./storage.js";
 export interface TableBufferingBindParams<TArgs = Record<string, any>> {
@@ -13,6 +14,8 @@ export interface TableBufferingBindParams<TArgs = Record<string, any>> {
     /** True on the second bind pass, after the connector resolved the secrets
      *  requested via the onBind `lookupSecret*` return fields on the first pass. */
     resolvedSecretsProvided: boolean;
+    /** Resolved names aligned with the complete logical argument order. */
+    argumentNames?: (string | null)[] | null;
 }
 export interface TableBufferingParams<TArgs = Record<string, any>> {
     args: TArgs;
@@ -40,6 +43,12 @@ export interface TableBufferingConfig<TArgs = Record<string, any>, TState = any>
     args?: Record<string, VgiDataType>;
     namedArgs?: Record<string, VgiDataType>;
     argDefaults?: Record<string, any>;
+    /** Authoritative typed defaults: one row, defaulted parameters only. */
+    parameterDefaultValues?: VgiBatch | null;
+    /** Argument descriptions keyed by argument name. */
+    argDocs?: Record<string, string>;
+    /** Discovery constraints, also enforced for scalar arguments at bind. */
+    argConstraints?: Record<string, ArgumentConstraints>;
     /** Bind: default passes through input schema. May be async. Return non-empty
      *  `lookupSecret*` lists on the first pass to request DuckDB secrets; the
      *  connector then re-binds with `resolvedSecretsProvided` and the resolved

package/dist/functions/table-in-out.d.ts

@@ -2,6 +2,7 @@ import { type VgiSchema, type VgiDataType, type VgiBatch } from "../arrow/index.
 import type { OutputCollector } from "@query-farm/vgi-rpc";
 import type { BindRequest, InitRequest, GlobalInitResponse } from "../protocol/types.js";
 import type { VgiFunction, FunctionExample } from "./types.js";
+import type { ArgumentConstraints } from "../arguments/argument-spec.js";
 import { type PushdownFilters } from "../filter-pushdown/index.js";
 import { FunctionStability } from "../types.js";
 import { BoundStorage } from "./storage.js";
@@ -10,6 +11,8 @@ export interface TableInOutBindParams<TArgs = Record<string, any>> {
     bindCall: BindRequest;
     settings: Record<string, any>;
     secrets: Record<string, Record<string, any>>;
+    /** Resolved names aligned with the complete logical argument order. */
+    argumentNames?: (string | null)[] | null;
 }
 export interface TableInOutProcessParams<TArgs = Record<string, any>> {
     args: TArgs;
@@ -52,6 +55,12 @@ export interface TableInOutConfig<TArgs = Record<string, any>, TState = null> {
     namedArgs?: Record<string, VgiDataType>;
     /** Argument defaults */
     argDefaults?: Record<string, any>;
+    /** Authoritative typed defaults: one row, defaulted parameters only. */
+    parameterDefaultValues?: VgiBatch | null;
+    /** Argument descriptions keyed by argument name. */
+    argDocs?: Record<string, string>;
+    /** Discovery constraints, also enforced for scalar arguments at bind. */
+    argConstraints?: Record<string, ArgumentConstraints>;
     /** Bind: default passes through input schema. May be async. */
     onBind?: (params: TableInOutBindParams<TArgs>) => {
         outputSchema: VgiSchema;
@@ -140,8 +149,12 @@ export interface RowTransformConfig<TArgs = Record<string, any>> {
     /** Named (string-position) args stay bind-time scalars on `params.args`. */
     namedArgs?: Record<string, VgiDataType>;
     argDefaults?: Record<string, any>;
+    /** Authoritative typed defaults: one row, defaulted parameters only. */
+    parameterDefaultValues?: VgiBatch | null;
     /** Per-argument descriptions keyed by arg name (surfaced as `vgi_doc`). */
     argDocs?: Record<string, string>;
+    /** Discovery constraints, also enforced for named scalar arguments at bind. */
+    argConstraints?: Record<string, ArgumentConstraints>;
     /** Bind: return the output schema. The input schema (the declared per-row
      *  columns, typed by the C++ bind) is on `params.bindCall.input_schema`. */
     onBind: (params: TableInOutBindParams<TArgs>) => {

package/dist/functions/table.d.ts

@@ -1,5 +1,6 @@
-import { type VgiSchema, type VgiDataType } from "../arrow/index.js";
+import { type VgiSchema, type VgiBatch, type VgiDataType } from "../arrow/index.js";
 import type { OutputCollector } from "@query-farm/vgi-rpc";
+import type { PlanResult, TableFunctionPlanRequest } from "../protocol/serializers/splits.js";
 import type { BindRequest, InitRequest, GlobalInitResponse, TableCardinality } from "../protocol/types.js";
 import type { VgiFunction, FunctionExample } from "./types.js";
 import { type ArgumentConstraints } from "../arguments/argument-spec.js";
@@ -13,6 +14,8 @@ export interface TableBindParams<TArgs = Record<string, any>> {
     settings: Record<string, any>;
     secrets: Record<string, Record<string, any>>;
     resolvedSecretsProvided: boolean;
+    /** Resolved names aligned with the complete logical argument order. */
+    argumentNames?: (string | null)[] | null;
 }
 export interface TableProcessParams<TArgs = Record<string, any>> {
     args: TArgs;
@@ -22,6 +25,15 @@ export interface TableProcessParams<TArgs = Record<string, any>> {
     settings: Record<string, any>;
     secrets: Record<string, Record<string, any>>;
     pushdownFilters?: PushdownFilters;
+    /**
+     * The verified payloads of the splits this init claimed, in the order given,
+     * or undefined when this is not a split scan.
+     *
+     * Undefined is meaningfully different from an empty array: undefined means
+     * the client did not plan (a split-only function should fail loudly rather
+     * than answer the same query differently), empty means a claim of no work.
+     */
+    splitPayloads?: Uint8Array[];
     storage?: BoundStorage;
     /**
      * AT (TIMESTAMP|VERSION) clause for this scan, or `undefined` when the scan
@@ -54,6 +66,8 @@ export interface TableFunctionConfig<TArgs = Record<string, any>, TState = null>
     argDocs?: Record<string, string>;
     /** Argument defaults */
     argDefaults?: Record<string, any>;
+    /** Authoritative typed defaults: one row, defaulted parameters only. */
+    parameterDefaultValues?: VgiBatch | null;
     /**
      * Per-argument discovery constraints (choices / ge / le / gt / lt / pattern),
      * keyed by argument name. Surfaced via `vgi_function_arguments()` for agent
@@ -91,6 +105,40 @@ export interface TableFunctionConfig<TArgs = Record<string, any>, TState = null>
     process: (params: TableProcessParams<TArgs>, state: TState, out: OutputCollector) => void | Promise<void>;
     /** Cardinality hints */
     cardinality?: (params: TableBindParams<TArgs>) => TableCardinality | Promise<TableCardinality>;
+    /**
+     * Divide this scan into named, independently redeemable splits.
+     *
+     * Declaring it (together with `meta.supportsSplits`) is what opts a function
+     * into the split path; omitting it means the whole scan is one unit of work.
+     *
+     * A split *names* work rather than describing it. "These three files at
+     * version 47" survives a retry; "rows 0-999 of whatever this returns now"
+     * does not — and a distributed engine WILL retry, so the difference is
+     * correctness, not tidiness. The same split may also be redeemed more than
+     * once (recursive CTEs, re-collected DataFrames, task retry) and may be
+     * abandoned mid-stream (LIMIT, TopK, an empty join build side); neither is an
+     * error.
+     *
+     * Set only `payload` on each split. The framework stamps the consistency
+     * anchor, the bind fingerprint and (where a key exists) the seal.
+     *
+     * Size splits into comparable units of work and honour `targetSplitBytes`: a
+     * claiming client treats them as interchangeable because it cannot see
+     * per-split cost, so wildly uneven splits leave its makespan bounded by the
+     * largest one.
+     */
+    plan?: (params: TableBindParams<TArgs>, request: TableFunctionPlanRequest) => PlanResult | Promise<PlanResult>;
+    /**
+     * Called on a split init with the VERIFIED payloads for the splits this
+     * connection claimed — the envelope is already opened and stripped, so
+     * unverified bytes never reach here.
+     *
+     * Any state carried from planning to reading must live in cross-process
+     * storage keyed by `execution_id`: the process that plans is, in the general
+     * case, not the process that reads — and under a distributed engine it is not
+     * even the same host.
+     */
+    onSplit?: (payloads: Uint8Array[], params: TableBindParams<TArgs>) => void | Promise<void>;
     /**
      * Per-column statistics for the function's output. Returned to DuckDB via
      * the `table_function_statistics` RPC; the optimizer uses min/max to
@@ -115,7 +163,10 @@ export interface TableFunctionConfig<TArgs = Record<string, any>, TState = null>
     /** Opt in to DuckDB's late-materialization SEMI-join rewrite; requires a
      *  UNIQUE, snapshot-stable rowid column. FunctionInfo.late_materialization. */
     lateMaterialization?: boolean;
-    supportedExpressionFilters?: string[];
+    filterSemanticProfiles?: string[];
+    additionalFilterFunctions?: import("./types.js").FilterFunctionCapability[];
+    runtimeFilterAlgorithms?: import("./types.js").FilterFunctionCapability[];
+    filterEvaluationContexts?: import("./types.js").EvaluationContextCapability[];
     autoApplyFilters?: boolean;
     stability?: FunctionStability;
     examples?: FunctionExample[];
@@ -134,5 +185,24 @@ export interface TableFunctionConfig<TArgs = Record<string, any>, TState = null>
     supportsBatchIndex?: boolean;
     /** Hive-style partition-columns mode; FunctionInfo.partition_kind. */
     partitionKind?: "NOT_PARTITIONED" | "SINGLE_VALUE_PARTITIONS" | "OVERLAPPING_PARTITIONS" | "DISJOINT_PARTITIONS";
+    /**
+     * This function divides its scan into named, independently redeemable splits;
+     * FunctionInfo.supports_splits. Declare it together with `plan` and `onSplit`.
+     *
+     * It is what a distributed engine reads to decide it can retry a task against
+     * this function, and what makes the client call `plan()` at all — without it a
+     * split-capable function is scanned as one undivided unit, silently.
+     */
+    supportsSplits?: boolean;
+    /**
+     * How long a minted split token stays redeemable, or undefined for UNBOUNDED
+     * (NOT "expires immediately"); FunctionInfo.split_token_ttl_seconds.
+     *
+     * A client refuses a plan whose TTL is below its own scheduling horizon,
+     * because an expired token is a failed query rather than a degradation:
+     * nothing re-plans when one expires, since a distributed engine retries the
+     * serialized task it was handed and has no path back to the planner.
+     */
+    splitTokenTtlSeconds?: number;
 }
 export declare function defineTableFunction<TArgs = Record<string, any>, TState = null>(config: TableFunctionConfig<TArgs, TState>): VgiFunction;