@query-farm/vgi 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "TypeScript framework for extending DuckDB with user-defined functions via the Vector Gateway Interface (VGI) over Arrow IPC.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Query Farm LLC (https://query.farm)",

package/src/functions/aggregate.ts

@@ -15,7 +15,11 @@
 
 import { type VgiSchema, schema, type VgiField, field, type VgiBatch, type VgiDataType, nullType, isNull } from "../arrow/index.js";
 import type { Arguments } from "../arguments/arguments.js";
-import type { ArgumentSpec } from "../arguments/argument-spec.js";
+import {
+  constraintSpecFields,
+  type ArgumentSpec,
+  type ArgumentConstraints,
+} from "../arguments/argument-spec.js";
 import type {
   FunctionMeta,
   VgiFunction,
@@ -123,6 +127,13 @@ 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>;
+  /**
+   * Per-argument discovery constraints (choices / ge / le / gt / lt / pattern),
+   * keyed by argument name. Surfaced via `vgi_function_arguments()` and enforced
+   * at aggregate_bind for const params: a value violating a declared constraint
+   * fails the bind with an ArgumentValidationError.
+   */
+  argConstraints?: Record<string, ArgumentConstraints>;
 
   initialState: (params: AggregateBindParams<TArgs>) => TState;
   /**
@@ -342,6 +353,7 @@ export function defineAggregate<TArgs = Record<string, any>, TState = any>(
         isAnyType,
         isVarargs: varargsSet.has(name),
         isConst,
+        ...constraintSpecFields(config.argConstraints?.[name]),
       });
     }
   }

package/src/functions/table.ts

@@ -29,7 +29,12 @@ import type {
   StreamHandlers,
   FunctionExample,
 } from "./types.js";
-import type { ArgumentSpec } from "../arguments/argument-spec.js";
+import {
+  constraintSpecFields,
+  validateConstConstraints,
+  type ArgumentSpec,
+  type ArgumentConstraints,
+} from "../arguments/argument-spec.js";
 import { batchToScalarDict, batchToSecretDict, projectSchema, safeNumber } from "../util/arrow/index.js";
 import {
   buildJoinKeysLookup,
@@ -166,6 +171,13 @@ export interface TableFunctionConfig<
   argDocs?: Record<string, string>;
   /** Argument defaults */
   argDefaults?: Record<string, any>;
+  /**
+   * Per-argument discovery constraints (choices / ge / le / gt / lt / pattern),
+   * keyed by argument name. Surfaced via `vgi_function_arguments()` for agent
+   * discovery AND enforced at bind: a value violating a declared constraint
+   * fails the bind with an ArgumentValidationError.
+   */
+  argConstraints?: Record<string, ArgumentConstraints>;
   /** Names of args that accept variable number of arguments */
   varargs?: string[];
   /** Bind: return output schema. May be async — handlers `await` the result. */
@@ -273,6 +285,7 @@ export function defineTableFunction<
         isAnyType: isAny,
         isVarargs: varargsSet.has(name),
         doc: config.argDocs?.[name],
+        ...constraintSpecFields(config.argConstraints?.[name]),
       });
     }
   }
@@ -318,6 +331,9 @@ export function defineTableFunction<
       }
       // Arrow Int64 values come through as BigInt — coerce to number
       if (typeof val === "bigint") val = safeNumber(val);
+      // Enforce declared constraints at bind (table args are all bind-time).
+      const constraints = config.argConstraints?.[spec.name];
+      if (constraints) validateConstConstraints(spec.name, constraints, val);
       args[spec.name] = val;
     }
     return args as TArgs;

package/src/protocol/handlers/aggregate.ts

@@ -32,6 +32,7 @@ import {
   type AggregateBindParams,
 } from "../../functions/aggregate.js";
 import { Arguments } from "../../arguments/arguments.js";
+import { validateConstConstraints } from "../../arguments/argument-spec.js";
 import {
   REQUEST_PARAMS_SCHEMA,
   RESULT_BINARY_SCHEMA,
@@ -310,8 +311,9 @@ function extractArgMap(
     }
   }
   for (let i = 0; i < constNames.length; i++) {
+    let v: any;
     try {
-      let v = args.get(i);
+      v = args.get(i);
       // Decode DECIMAL scalars (DuckDB serializes 0.5-style literals as
       // DECIMAL(2,1), which Arrow stores as the unscaled integer — a raw
       // BigInt here). Scale back to float using the declared scale.
@@ -323,14 +325,22 @@ function extractArgMap(
       } else if (typeof v === "bigint") {
         v = Number(v);
       }
-      out[constNames[i]] = v;
     } catch {
       // args.get throws when the arg isn't set — fall back to the declared
       // default so aggregates called without an explicit const value still
       // see it in update/finalize.
       const def = cfg.argDefaults?.[constNames[i]];
       if (def !== undefined) out[constNames[i]] = def;
+      continue;
     }
+    // Enforce declared constraints on the supplied value. This sits OUTSIDE the
+    // try above so a constraint violation propagates as a bind error rather than
+    // being swallowed and silently replaced by the default.
+    const constraints = cfg.argConstraints?.[constNames[i]];
+    if (constraints !== undefined) {
+      validateConstConstraints(constNames[i], constraints, v);
+    }
+    out[constNames[i]] = v;
   }
   // Non-const args aren't in the wire Arguments, but users may still want
   // defaults surfaced for `params.args` — apply them here.