@query-farm/vgi 0.29.0 → 0.29.1

package/src/functions/table-in-out.ts

@@ -3,7 +3,7 @@
 // Two-phase: INPUT phase receives and transforms batches,
 // FINALIZE phase emits final results.
 
-import { type VgiSchema, schema, type VgiField, type VgiDataType, type VgiBatch, nullType, withBatchMetadata } from "../arrow/index.js";
+import { type VgiSchema, schema, type VgiField, type VgiDataType, type VgiBatch, nullType, withBatchMetadata, serializeBatch, deserializeBatch } from "../arrow/index.js";
 import type { OutputCollector } from "@query-farm/vgi-rpc";
 import { DEFAULT_MAX_WORKERS, TableInOutPhase } from "../types.js";
 import type {
@@ -18,20 +18,33 @@ import type {
   StreamHandlers,
   FunctionExample,
 } from "./types.js";
-import type { ArgumentSpec } from "../arguments/argument-spec.js";
-import { assertArrowType, assertArrowTypes, narrowArgValue } from "../arguments/argument-spec.js";
+import type { ArgumentConstraints, ArgumentSpec } from "../arguments/argument-spec.js";
+import {
+  assertArrowType,
+  assertArrowTypes,
+  constraintSpecFields,
+  narrowArgValue,
+  validateConstConstraints,
+} from "../arguments/argument-spec.js";
 import { batchToScalarDict, batchToSecretDict, projectSchema, projectBatch, emptyBatch, safeNumber } from "../util/arrow/index.js";
 import { CACHE_IF_MODIFIED_SINCE_KEY, CACHE_IF_NONE_MATCH_KEY } from "../cache-control.js";
 import {
-  buildJoinKeysLookup,
   deserializeFilters,
   FilteringOutputCollector,
   type PushdownFilters,
 } from "../filter-pushdown/index.js";
 import { FunctionStability } from "../types.js";
-import { BoundStorage, storage as defaultStorage } from "./storage.js";
+import { BoundStorage, storage as defaultStorage, FrameworkNS } from "./storage.js";
 import { serializeUserState, deserializeUserState } from "../protocol/state-serializer.js";
 
+/**
+ * State-log key the streaming FINALIZE drain uses within
+ * {@link FrameworkNS.STREAMING_FINALIZE}. There is exactly one flush per
+ * execution, so a single empty key is enough — matches vgi-python's
+ * `_STREAMING_FINALIZE_KEY = b""`.
+ */
+const STREAMING_FINALIZE_KEY = new Uint8Array(0);
+
 // ============================================================================
 // Table In-Out parameter bundles (reuse table function's)
 // ============================================================================
@@ -41,6 +54,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>> {
@@ -92,6 +107,12 @@ export interface TableInOutConfig<
   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; opaqueData?: Uint8Array }
@@ -147,6 +168,11 @@ export function defineTableInOutFunction<
         name,
         position: posIdx++,
         arrowType: type,
+        doc: config.argDocs?.[name],
+        ...constraintSpecFields(
+          config.argConstraints?.[name],
+          config.argDefaults?.[name],
+        ),
       });
     }
   }
@@ -165,6 +191,11 @@ export function defineTableInOutFunction<
         name,
         position: name, // string position = named arg
         arrowType: type,
+        doc: config.argDocs?.[name],
+        ...constraintSpecFields(
+          config.argConstraints?.[name],
+          config.argDefaults?.[name],
+        ),
       });
     }
   }
@@ -179,6 +210,7 @@ export function defineTableInOutFunction<
     examples: config.examples,
     categories: config.categories,
     tags: config.tags,
+    parameterDefaultValues: config.parameterDefaultValues,
     maxWorkers: config.maxWorkers,
     requiredSettings: config.requiredSettings,
     requiredSecrets: config.requiredSecrets,
@@ -198,6 +230,8 @@ export function defineTableInOutFunction<
       // Arrow Int64 arrives as bigint. Narrow when lossless, keep the
       // bigint when not — see narrowArgValue.
       val = narrowArgValue(val);
+      const constraints = config.argConstraints?.[spec.name];
+      if (constraints) validateConstConstraints(spec.name, constraints, val);
       args[spec.name] = val;
     }
     return args as TArgs;
@@ -218,6 +252,7 @@ export function defineTableInOutFunction<
           bindCall: request,
           settings,
           secrets,
+          argumentNames: request.argument_names ?? null,
         });
         return {
           output_schema: result.outputSchema,
@@ -280,9 +315,14 @@ export function defineTableInOutFunction<
       // Deserialize pushdown filters. Pass a join-keys column lookup so that
       // filters DuckDB promoted to join_keys (IN/OR lists, etc.) are
       // materialized as InFilters rather than silently dropped.
-      const joinKeysLookup = buildJoinKeysLookup(request.join_keys);
       const pushdownFilters = request.pushdown_filters
-        ? deserializeFilters(request.pushdown_filters, joinKeysLookup)
+        ? deserializeFilters(request.pushdown_filters, {
+          outputSchema: request.output_schema,
+          joinKeyBatches: request.join_keys,
+          extensionFunctions: meta.additionalFilterFunctions,
+          runtimeAlgorithms: meta.runtimeFilterAlgorithms,
+          evaluationContexts: meta.filterEvaluationContexts,
+        })
         : undefined;
 
       // Create BoundStorage for cross-phase/cross-worker data sharing
@@ -306,18 +346,41 @@ export function defineTableInOutFunction<
       const phase = request.phase;
 
       if (phase === TableInOutPhase.FINALIZE) {
-        // FINALIZE phase: producer mode.
-        // The actual collect+finalize work is deferred into the first
-        // producerFn call so the (now-async) FunctionStorage can be awaited
-        // there. Storing the materialized batches on the per-call state.
+        // FINALIZE phase: producer mode, drained by cursor out of the
+        // execution-scoped state log.
+        //
+        // Over HTTP a producer stream is strictly LOCK-STEP: at most one data
+        // batch per response, after which the worker hands back a continuation
+        // token and the client comes back for the next batch. A finalize()
+        // returning N batches therefore has to survive N-1 continuations — and
+        // a continuation rebuilds these handlers from scratch, with nothing of
+        // the previous turn left in memory.
+        //
+        // The prior shape kept the materialized batches on the handler object
+        // (a `batches` field beside `state`), and only `state` rides the state
+        // token. So the continuation found `batches == null` and re-ran the
+        // user's finalize() — whose inputs `boundStorage.collect()` had already
+        // DESTRUCTIVELY drained (DELETE ... RETURNING). Second call: no states,
+        // zero batches, immediate finish. The stream truncated after its first
+        // batch, silently, and only over HTTP (a byte-stream transport runs
+        // every tick inside one process, so the field survived).
+        //
+        // Same fix as vgi-python's BufferedFinalizeState: call the user's
+        // finalize() exactly ONCE, append each returned batch's IPC bytes to
+        // the state log under FrameworkNS.STREAMING_FINALIZE, and have every
+        // tick drain exactly ONE row past a cursor. Only the POSITION rides the
+        // state token, never the rows. finalize() is never re-run: its contract
+        // is to DRAIN accumulated state, so a second call is not obliged to
+        // return the same rows.
+        const finalizeLogKey = STREAMING_FINALIZE_KEY;
         return {
           outputSchema,
-          producerInit: () => ({ state: { batchIdx: 0 }, batches: null as VgiBatch[] | null }),
+          producerInit: () => ({ state: { cursor: -1, materialized: false } }),
           producerFn: async (
-            pState: { state: { batchIdx: number }; batches: VgiBatch[] | null },
+            pState: { state: { cursor: number; materialized: boolean } },
             out: OutputCollector
           ) => {
-            if (pState.batches == null) {
+            if (!pState.state.materialized) {
               const finalizeStates: TState[] = [];
               if (accumulatedState != null) {
                 finalizeStates.push(accumulatedState as TState);
@@ -336,24 +399,55 @@ export function defineTableInOutFunction<
                     : (null as TState),
                 );
               }
-              pState.batches = config.finalize
+              const batches: VgiBatch[] = config.finalize
                 ? await config.finalize(processParams, finalizeStates)
                 : [];
+              for (const batch of batches) {
+                await boundStorage.stateAppend(
+                  FrameworkNS.STREAMING_FINALIZE,
+                  finalizeLogKey,
+                  serializeBatch(batch),
+                );
+              }
+              // Set before the first emit so the flag is part of the userState
+              // this turn serializes — a continuation must never re-run
+              // finalize(), even when the log came back empty.
+              pState.state.materialized = true;
             }
-            if (pState.state.batchIdx >= pState.batches.length) {
+            const rows = await boundStorage.stateLogScan(
+              FrameworkNS.STREAMING_FINALIZE,
+              finalizeLogKey,
+              pState.state.cursor,
+              1,
+            );
+            if (rows.length === 0) {
               out.finish();
               return;
             }
-            out.emit(pState.batches[pState.state.batchIdx]);
-            pState.state.batchIdx++;
-            if (pState.state.batchIdx >= pState.batches.length) {
-              out.finish();
-            }
+            const [logId, bytes] = rows[0];
+            out.emit(deserializeBatch(bytes) as unknown as VgiBatch);
+            pState.state.cursor = logId;
           },
         };
       }
 
-      // INPUT phase: exchange mode
+      // INPUT phase: exchange mode. Any phase other than FINALIZE falls
+      // through to here, including a missing/undefined phase -- i.e. a
+      // caller that drove this function via table_function() instead of
+      // table_in_out_function(input=...). Reject that immediately rather
+      // than silently degrading to an empty inputSchema below, which
+      // disables the transport layer's own schema-conformance check and
+      // leaves both sides waiting on each other forever (confirmed live: a
+      // non-terminating exchange/continuation loop against a real deployed
+      // worker, not an error).
+      if (request.bind_call.input_schema == null) {
+        throw new Error(
+          `${config.name}: is a table-in-out function (it requires an input row ` +
+            `stream) but no input schema was supplied -- call it via ` +
+            `table_in_out_function(input=...), not table_function().`,
+        );
+      }
+
       const state = config.initialState
         ? config.initialState(processParams)
         : (null as TState);
@@ -372,7 +466,7 @@ export function defineTableInOutFunction<
 
       return {
         outputSchema,
-        inputSchema: request.bind_call.input_schema ?? undefined,
+        inputSchema: request.bind_call.input_schema,
         exchangeInit: () => ({ state, processParams }),
         exchangeFn: async (
           eState: {
@@ -386,6 +480,7 @@ export function defineTableInOutFunction<
           // custom metadata (attached by the C++ WriteInputBatch), so process()
           // can answer a 0-row `notModified` batch instead of recomputing.
           applyRevalidationValidators(eState.processParams, input);
+          applyDynamicFilterUpdate(eState.processParams, input);
           // Bake emit metadata onto the batch (0-row HTTP survival), then
           // reconcile emitted batches to the (possibly projected) output schema
           // by name — a process() may emit its full declared schema and let the
@@ -394,8 +489,9 @@ export function defineTableInOutFunction<
           if (projIds) {
             wrappedOut = makeSchemaReconcilingCollector(wrappedOut, outputSchema);
           }
-          if (config.autoApplyFilters && pushdownFilters) {
-            wrappedOut = new FilteringOutputCollector(wrappedOut, pushdownFilters) as unknown as OutputCollector;
+          const currentFilters = eState.processParams.pushdownFilters;
+          if (config.autoApplyFilters && currentFilters) {
+            wrappedOut = new FilteringOutputCollector(wrappedOut, currentFilters) as unknown as OutputCollector;
           }
           await processFn(eState.processParams, eState.state, input, wrappedOut);
 
@@ -433,6 +529,29 @@ function applyRevalidationValidators(
   params.ifModifiedSince = md?.get(CACHE_IF_MODIFIED_SINCE_KEY);
 }
 
+function applyDynamicFilterUpdate(
+  params: { pushdownFilters?: PushdownFilters },
+  input: VgiBatch,
+): void {
+  const encoded = ((input as any)?.metadata as Map<string, string> | undefined)?.get("vgi_pushdown_filters");
+  if (!encoded) return;
+  if (!params.pushdownFilters) throw new Error("dynamic filter delta received without an initial snapshot");
+  if (new TextEncoder().encode(encoded).byteLength > (24 << 20)) {
+    throw new Error("base64 dynamic filter metadata exceeds the encoded-size limit");
+  }
+  if (encoded.length % 4 !== 0 ||
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) {
+    throw new Error("dynamic filter metadata is not valid base64");
+  }
+  const binary = (globalThis as any).atob
+    ? (globalThis as any).atob(encoded)
+    : Buffer.from(encoded, "base64").toString("binary");
+  const bytes = Uint8Array.from(binary, (character: string) => character.charCodeAt(0));
+  if (bytes.byteLength > (17 << 20)) throw new Error("dynamic filter IPC payload exceeds the encoded-size limit");
+  const current = params.pushdownFilters;
+  params.pushdownFilters = current.applyDelta(deserializeBatch(bytes));
+}
+
 /**
  * Wrap an OutputCollector so a pre-built batch emitted WITH metadata carries
  * that metadata on the batch object itself (merged over any metadata the
@@ -619,8 +738,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>) =>
@@ -687,6 +810,7 @@ export function defineRowTransformFunction<
         position: posIdx++,
         arrowType: type,
         doc: config.argDocs?.[name],
+        ...constraintSpecFields(config.argConstraints?.[name]),
       });
     }
   }
@@ -697,6 +821,7 @@ export function defineRowTransformFunction<
       arrowType: config.varargs.type,
       isVarargs: true,
       doc: config.varargs.doc ?? config.argDocs?.[config.varargs.name],
+      ...constraintSpecFields(config.argConstraints?.[config.varargs.name]),
     });
   }
   if (config.namedArgs) {
@@ -706,6 +831,10 @@ export function defineRowTransformFunction<
         position: name,
         arrowType: type,
         doc: config.argDocs?.[name],
+        ...constraintSpecFields(
+          config.argConstraints?.[name],
+          config.argDefaults?.[name],
+        ),
       });
     }
   }
@@ -720,6 +849,7 @@ export function defineRowTransformFunction<
     examples: config.examples,
     categories: config.categories,
     tags: config.tags,
+    parameterDefaultValues: config.parameterDefaultValues,
     maxWorkers: config.maxWorkers,
     requiredSettings: config.requiredSettings,
     requiredSecrets: config.requiredSecrets,
@@ -740,6 +870,8 @@ export function defineRowTransformFunction<
           : undefined;
       let val = request.arguments.get(spec.position, defaultVal ?? null);
       val = narrowArgValue(val);
+      const constraints = config.argConstraints?.[spec.name];
+      if (constraints) validateConstConstraints(spec.name, constraints, val);
       args[spec.name] = val;
     }
     return args as TArgs;
@@ -759,6 +891,7 @@ export function defineRowTransformFunction<
         bindCall: request,
         settings,
         secrets,
+        argumentNames: request.argument_names ?? null,
       });
       return {
         output_schema: result.outputSchema,
@@ -799,9 +932,14 @@ export function defineRowTransformFunction<
         ? projectSchema(projIds, request.output_schema)
         : request.output_schema;
 
-      const joinKeysLookup = buildJoinKeysLookup(request.join_keys);
       const pushdownFilters = request.pushdown_filters
-        ? deserializeFilters(request.pushdown_filters, joinKeysLookup)
+        ? deserializeFilters(request.pushdown_filters, {
+          outputSchema: request.output_schema,
+          joinKeyBatches: request.join_keys,
+          extensionFunctions: meta.additionalFilterFunctions,
+          runtimeAlgorithms: meta.runtimeFilterAlgorithms,
+          evaluationContexts: meta.filterEvaluationContexts,
+        })
         : undefined;
 
       const boundStorage = new BoundStorage(
@@ -828,9 +966,26 @@ export function defineRowTransformFunction<
         );
       }
 
+      if (request.bind_call.input_schema == null) {
+        // A caller drove this function via table_function() (or the bare
+        // producer path) instead of table_in_out_function(input=...) -- a
+        // blended row-transform function's positional args ARE its per-row
+        // input columns, so it cannot run with no input stream at all. Left
+        // unguarded, this doesn't fail here -- it silently degrades to an
+        // empty inputSchema, which disables the transport layer's own
+        // schema-conformance check downstream and leaves both sides waiting
+        // on each other forever: confirmed live, a non-terminating exchange/
+        // continuation loop against a real deployed worker, not an error.
+        throw new Error(
+          `${config.name}: is a table-in-out function (its positional args are ` +
+            `per-row input columns) but no input schema was supplied -- call it ` +
+            `via table_in_out_function(input=...), not table_function().`,
+        );
+      }
+
       return {
         outputSchema,
-        inputSchema: request.bind_call.input_schema ?? undefined,
+        inputSchema: request.bind_call.input_schema,
         exchangeInit: () => ({ state: null, processParams }),
         exchangeFn: async (
           eState: { state: null; processParams: RowTransformProcessParams<TArgs> },
@@ -838,12 +993,14 @@ export function defineRowTransformFunction<
           out: OutputCollector,
         ) => {
           applyRevalidationValidators(eState.processParams, input);
+          applyDynamicFilterUpdate(eState.processParams, input);
           let wrappedOut: OutputCollector = makeMetadataBakingCollector(out);
           if (projIds) {
             wrappedOut = makeSchemaReconcilingCollector(wrappedOut, outputSchema);
           }
-          if (config.autoApplyFilters && pushdownFilters) {
-            wrappedOut = new FilteringOutputCollector(wrappedOut, pushdownFilters) as unknown as OutputCollector;
+          const currentFilters = eState.processParams.pushdownFilters;
+          if (config.autoApplyFilters && currentFilters) {
+            wrappedOut = new FilteringOutputCollector(wrappedOut, currentFilters) as unknown as OutputCollector;
           }
           await config.process(eState.processParams, input, wrappedOut);
         },

package/src/functions/table.ts

@@ -43,7 +43,6 @@ import {
 import { assertArrowType, assertArrowTypes } from "../arguments/argument-spec.js";
 import { batchToScalarDict, batchToSecretDict, projectSchema, safeNumber } from "../util/arrow/index.js";
 import {
-  buildJoinKeysLookup,
   deserializeFilters,
   FilteringOutputCollector,
   type PushdownFilters,
@@ -62,9 +61,16 @@ import { CACHE_IF_MODIFIED_SINCE_KEY, CACHE_IF_NONE_MATCH_KEY } from "../cache-c
 // Base64-decode a string into raw bytes. Used to unpack the dynamic filter
 // update DuckDB attaches to each tick batch's custom metadata.
 function base64Decode(s: string): Uint8Array {
+  if (new TextEncoder().encode(s).byteLength > (24 << 20)) {
+    throw new Error("base64 dynamic filter metadata exceeds the encoded-size limit");
+  }
+  if (s.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(s)) {
+    throw new Error("dynamic filter metadata is not valid base64");
+  }
   const bin = (globalThis as any).atob ? (globalThis as any).atob(s) : Buffer.from(s, "base64").toString("binary");
   const out = new Uint8Array(bin.length);
   for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  if (out.byteLength > (17 << 20)) throw new Error("dynamic filter IPC payload exceeds the encoded-size limit");
   return out;
 }
 
@@ -140,6 +146,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>> {
@@ -199,6 +207,8 @@ export interface TableFunctionConfig<
   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
@@ -310,7 +320,10 @@ export interface TableFunctionConfig<
   /** 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[];
@@ -373,7 +386,10 @@ export function defineTableFunction<
         isAnyType: isAny,
         isVarargs: varargsSet.has(name),
         doc: config.argDocs?.[name],
-        ...constraintSpecFields(config.argConstraints?.[name]),
+        ...constraintSpecFields(
+          config.argConstraints?.[name],
+          config.argDefaults?.[name],
+        ),
       });
     }
   }
@@ -386,11 +402,15 @@ export function defineTableFunction<
     filterPushdown: config.filterPushdown,
     samplingPushdown: config.samplingPushdown,
     lateMaterialization: config.lateMaterialization,
-    supportedExpressionFilters: config.supportedExpressionFilters,
+    filterSemanticProfiles: config.filterSemanticProfiles,
+    additionalFilterFunctions: config.additionalFilterFunctions,
+    runtimeFilterAlgorithms: config.runtimeFilterAlgorithms,
+    filterEvaluationContexts: config.filterEvaluationContexts,
     autoApplyFilters: config.autoApplyFilters,
     examples: config.examples,
     categories: config.categories,
     tags: config.tags,
+    parameterDefaultValues: config.parameterDefaultValues,
     maxWorkers: config.maxWorkers,
     requiredSettings: config.requiredSettings,
     requiredSecrets: config.requiredSecrets,
@@ -442,6 +462,7 @@ export function defineTableFunction<
       const result = await config.onBind({
         args, bindCall: request, settings, secrets,
         resolvedSecretsProvided: request.resolved_secrets_provided ?? false,
+        argumentNames: request.argument_names ?? null,
       });
       return {
         output_schema: result.outputSchema,
@@ -525,9 +546,15 @@ export function defineTableFunction<
       // Deserialize pushdown filters. Pass a join-keys column lookup so that
       // filters DuckDB promoted to join_keys (IN/OR lists, etc.) are
       // materialized as InFilters rather than silently dropped.
-      const joinKeysLookup = buildJoinKeysLookup(request.join_keys);
+      const filterOptions = {
+        outputSchema: request.output_schema,
+        joinKeyBatches: request.join_keys,
+        extensionFunctions: meta.additionalFilterFunctions,
+        runtimeAlgorithms: meta.runtimeFilterAlgorithms,
+        evaluationContexts: meta.filterEvaluationContexts,
+      };
       const pushdownFilters = request.pushdown_filters
-        ? deserializeFilters(request.pushdown_filters, joinKeysLookup)
+        ? deserializeFilters(request.pushdown_filters, filterOptions)
         : undefined;
 
       const boundStorage = new BoundStorage(globalStorage, response.execution_id);
@@ -546,6 +573,20 @@ export function defineTableFunction<
         atValue: request.bind_call.at_value ?? undefined,
       };
 
+      if (request.phase != null) {
+        // Mirror image of the table-in-out guard: this is a plain producer
+        // (no input stream), but the caller sent a table-in-out init phase --
+        // i.e. drove it via table_in_out_function() instead of
+        // table_function(). Reject immediately rather than silently ignoring
+        // the phase/input stream and running as an ordinary producer while
+        // the caller is left feeding batches nobody reads.
+        throw new Error(
+          `${config.name}: is a plain table function (it takes no input row ` +
+            `stream) but was called with an init phase set -- call it via ` +
+            `table_function(), not table_in_out_function().`,
+        );
+      }
+
       const state = config.initialState
         ? config.initialState(processParams)
         : (null as TState);
@@ -570,23 +611,20 @@ export function defineTableFunction<
           if (ifModifiedSince !== undefined) pState.processParams.ifModifiedSince = ifModifiedSince;
 
           // Dynamic filter pushdown: DuckDB's Top-N optimizer tightens filters
-          // between ticks and serializes the current filter into the tick
+          // between ticks and serializes an atomic v2 delta into the tick
           // batch's custom metadata under `vgi_pushdown_filters` (base64 of a
-          // filter IPC stream). Decode and overwrite the current pushdown
-          // filters so process() sees the updated value.
+          // filter IPC stream). Apply it to the prior snapshot so process()
+          // sees the revised advisory predicate state.
           const encoded = tickMetadata.get("vgi_pushdown_filters");
           if (!encoded) return;
-          try {
-            const bytes = base64Decode(encoded);
-            const filterBatch = deserializeFilterBatch(bytes);
-            if (filterBatch) {
-              const updated = deserializeFilters(filterBatch, joinKeysLookup);
-              pState.processParams.pushdownFilters = updated;
-            }
-          } catch {
-            // Malformed dynamic-filter update: keep the previous filter. Not
-            // fatal — this is a best-effort optimization hint from DuckDB.
-          }
+          const current = pState.processParams.pushdownFilters;
+          if (!current) throw new Error("dynamic filter delta received without an initial snapshot");
+          const bytes = base64Decode(encoded);
+          const filterBatch = deserializeFilterBatch(bytes);
+          if (!filterBatch) throw new Error("dynamic filter metadata must contain one RecordBatch");
+          // Assignment happens only after complete validation, so a rejected
+          // delta leaves the immutable prior state intact.
+          pState.processParams.pushdownFilters = current.applyDelta(filterBatch);
         },
         producerFn: async (
           pState: { state: TState; processParams: TableProcessParams<TArgs> },

package/src/functions/types.ts

@@ -6,6 +6,7 @@ import type { OutputCollector } from "@query-farm/vgi-rpc";
 import type {
   FunctionStability,
   NullHandling,
+  ArgumentMonotonicity,
   OrderPreservation,
   OrderDependence,
   DistinctDependence,
@@ -34,14 +35,33 @@ export interface FunctionExample {
   expectedOutput?: string;
 }
 
+export interface FilterFunctionCapability {
+  namespace: string;
+  name: string;
+  version: number;
+}
+
+export interface EvaluationContextCapability {
+  profile: string;
+  providerFingerprint?: string | null;
+}
+
 export interface FunctionMeta {
   name: string;
   description?: string;
   stability?: FunctionStability;
   nullHandling?: NullHandling;
+  /** Scalar-only claims in argument declaration order. A vararg is one slot. */
+  argumentMonotonicity?: ArgumentMonotonicity[] | null;
   examples?: FunctionExample[];
   categories?: string[];
   tags?: Record<string, string>;
+  /**
+   * Authoritative typed parameter defaults. The batch must contain one row
+   * and only defaulted parameters, in signature order; a present null is an
+   * explicit null default. `vgi_default` field metadata remains discovery-only.
+   */
+  parameterDefaultValues?: VgiBatch | null;
   projectionPushdown?: boolean;
   filterPushdown?: boolean;
   samplingPushdown?: boolean;
@@ -54,7 +74,10 @@ export interface FunctionMeta {
    * for tables whose worker also guarantees a UNIQUE, snapshot-stable rowid.
    */
   lateMaterialization?: boolean;
-  supportedExpressionFilters?: string[];
+  filterSemanticProfiles?: string[];
+  additionalFilterFunctions?: FilterFunctionCapability[];
+  runtimeFilterAlgorithms?: FilterFunctionCapability[];
+  filterEvaluationContexts?: EvaluationContextCapability[];
   autoApplyFilters?: boolean;
   preservesOrder?: OrderPreservation;
   maxWorkers?: number;